Commit | Line | Data |
---|---|---|
9787c8a8 | 1 | .\" -*-nroff-*- |
2 | .de VS | |
3 | .sp 1 | |
4 | .RS | |
5 | .nf | |
6 | .ft B | |
7 | .. | |
8 | .de VE | |
9 | .ft R | |
10 | .fi | |
11 | .RE | |
12 | .sp 1 | |
13 | .. | |
fbf20b5b | 14 | .TH pool 3 "7 July 2000" "Straylight/Edgeware" "mLib utilities library" |
9787c8a8 | 15 | .SH "NAME" |
16 | pool \- resource pool management | |
17 | .\" @pool_alloc | |
18 | .\" @pool_strdup | |
c5775f49 | 19 | .\" @pool_init |
9787c8a8 | 20 | .\" @pool_create |
21 | .\" @pool_destroy | |
22 | .\" @pool_sub | |
23 | .\" @pool_add | |
24 | .\" @POOL_ADD | |
25 | .\" @pool_fopen | |
26 | .\" @pool_fclose | |
27 | .\" @pool_subarena | |
28 | .SH "SYNOPSIS" | |
29 | .nf | |
30 | .B "#include <mLib/pool.h>" | |
d056fbdf | 31 | .PP |
4729aa69 | 32 | .B "typedef struct { ...\& } pool;" |
d056fbdf | 33 | .PP |
adec5584 | 34 | .ta 2n |
4729aa69 | 35 | .B "typedef struct {" |
adec5584 MW |
36 | .B " pool_resource *next;" |
37 | .BI " void (*destroy)(pool_resource *" r ); | |
4729aa69 | 38 | .B "} pool_resource;" |
d056fbdf | 39 | .PP |
4729aa69 | 40 | .B "typedef struct {" |
adec5584 MW |
41 | .B " FILE *fp;" |
42 | .B " ..." | |
4729aa69 | 43 | .B "} pool_file;" |
d056fbdf | 44 | .PP |
c5775f49 | 45 | .BI "void pool_init(pool *" p ", arena *" a ); |
9787c8a8 | 46 | .BI "pool *pool_create(arena *" a ); |
47 | .BI "pool *pool_sub(pool *" p ); | |
48 | .BI "void pool_destroy(pool *" p ); | |
adec5584 | 49 | .ta \w'\fBvoid pool_add('u |
9787c8a8 | 50 | .BI "void pool_add(pool *" p ", pool_resource *" r , |
adec5584 | 51 | .BI " void (*" dfn ")(pool_resource *" r )); |
9787c8a8 | 52 | .BI "void *pool_alloc(pool *" p ", size_t " sz ); |
53 | .BI "char *pool_strdup(pool *" p ", const char *" s ); | |
54 | .BI "pool_file *pool_fopen(pool *" p ", const char *" file ", const char *" how ); | |
55 | .BI "int pool_fclose(pool_file *" pf ); | |
56 | .BI "subarena *pool_subarena(pool *" p ); | |
d056fbdf | 57 | .PP |
adec5584 | 58 | .ta \w'\fBvoid POOL_ADD('u |
9787c8a8 | 59 | .BI "void POOL_ADD(pool *" p ", pool_resource *" r , |
adec5584 | 60 | .BI " void (*" dfn ")(pool_resource *" r )); |
9787c8a8 | 61 | .fi |
62 | .SH "DESCRIPTION" | |
63 | .SS "Overview" | |
64 | A | |
65 | .I "resource pool" | |
66 | is a collection of resources (e.g., memory, files) which may be disposed | |
67 | of simultaneously. | |
68 | .PP | |
69 | A pool may be a | |
70 | .IR "root pool" , | |
71 | in which case it stands on its own, or it may be a | |
d4efbcd9 | 72 | .IR "subpool" |
9787c8a8 | 73 | of another pool (which may in turn either be a root pool or a subpool of |
74 | another). | |
75 | .PP | |
76 | Pools manage memory efficiently. Memory is allocated in large chunks | |
77 | from an | |
78 | .BR arena (3), | |
79 | and given out as necessary to callers. There is no way of freeing | |
80 | memory dynamically; instead, the memory allocated by a pool is freed | |
81 | when the pool is destroyed. While allocation is rapid, there is waste | |
82 | because the allocator has to ensure that blocks are properly aligned. | |
83 | Since pools offer an arena interface, it is possible to build a | |
84 | .BR subarena (3) | |
85 | over them. This also enables memory in the subarena to be reclaimed | |
86 | when the pool is destroyed. | |
87 | .PP | |
88 | Other resources (e.g., file handles) may be added to the pool. The pool | |
89 | will automatically release any resources it has when it's destroyed. | |
90 | Attaching resources to an appropriate pool can therefore be a useful way | |
91 | of avoiding memory leaks. | |
92 | .SS "Creating and destroying pools" | |
93 | A new root pool is created using | |
94 | .BR pool_create , | |
95 | passing it an arena from which it can allocate large memory blocks. | |
c5775f49 | 96 | Alternatively, you can allocate a |
97 | .B pool | |
98 | structure from somewhere and initialize it by passing its address and an | |
99 | arena to | |
100 | .BR pool_init . | |
9787c8a8 | 101 | .PP |
102 | A subpool is created by calling | |
103 | .BR pool_sub , | |
104 | naming the parent pool. | |
105 | .PP | |
106 | Pools are destroyed by passing them to | |
107 | .BR pool_destroy . | |
c5775f49 | 108 | Pools created by |
109 | .B pool_create | |
110 | are completely destroyed, since the memory containing the pool structure | |
111 | is allocated from the pool itself. Subpools and pools allocated by the | |
112 | caller and initialized by | |
113 | .BR pool_init , | |
114 | on the other hand, are | |
115 | allocated from a parent pool, and may be reused after being `destroyed'. | |
9787c8a8 | 116 | .SS "Memory allocation" |
117 | Memory is allocated from a pool by calling | |
118 | .BR pool_alloc , | |
119 | passing it the pool and the size of memory requested. There is an | |
120 | interface for copying strings, | |
121 | .BR pool_strdup , | |
122 | since this is a common operation. Note that there is no | |
123 | .BR pool_free : | |
124 | if this is important, either use the pool's arena | |
125 | .B p->pa | |
126 | directly or create a subpool. | |
127 | .PP | |
128 | A pool provides an | |
129 | .BR arena (3) | |
130 | interface, | |
131 | .BR p->a , | |
132 | which can be passed to other components to cause them to use the pool | |
133 | for memory allocation. | |
134 | .SS "Other resources" | |
135 | Pool resources have a header of type | |
136 | .B pool_resource | |
4729aa69 MW |
137 | with the structure shown in the synopsis. Resources are added to the |
138 | pool by passing a pointer to the pool, the resource block and a | |
139 | destruction function to | |
9787c8a8 | 140 | .BR pool_add . |
141 | .PP | |
142 | If your resource is freed before the pool is destroyed, manually zero | |
143 | the | |
144 | .B destroy | |
145 | field in the resource header to let the pool manager know not to free | |
146 | the resource again. | |
147 | .PP | |
148 | It's usual to allocate the resource structures from the pool's arena so | |
149 | that they're automatically freed when the pool is destroyed. | |
150 | .PP | |
151 | A | |
152 | .BR subarena (3) | |
153 | may be created for a particular pool by calling | |
154 | .BR pool_subarena . | |
155 | The subarena and its contents will be freed automatically when the pool | |
156 | is destroyed. | |
157 | .PP | |
158 | Files may be opened and registered with a pool by | |
159 | .BR pool_fopen : | |
160 | the | |
161 | .I pool | |
162 | argument specifies which pool, and the | |
163 | .I file | |
164 | and | |
165 | .I how | |
166 | arguments are passed to the standard | |
167 | .BR fopen (3) | |
168 | function. The return value is a pointer to a | |
169 | .B pool_file | |
170 | structure, containing a member | |
171 | .B fp | |
172 | which is the actual file handle. Don't call | |
173 | .B fclose | |
174 | directly on the file handle: instead pass the whole structure to | |
175 | .B pool_fclose | |
176 | which will ensure that it doesn't get closed twice by accident. It's | |
177 | advisable to close files by hand, to prevent the process from running | |
178 | out; it's just not a disaster if you forget by accident. | |
179 | .SH "SEE ALSO" | |
180 | .BR alloc (3), | |
181 | .BR arena (3), | |
182 | .BR mLib (3), | |
183 | .BR subarena (3). | |
184 | .SH AUTHOR | |
9b5ac6ff | 185 | Mark Wooding, <mdw@distorted.org.uk> |