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