14 .TH pool 3 "7 July 2000" "Straylight/Edgeware" "mLib utilities library"
16 pool \- resource pool management
30 .B "#include <mLib/pool.h>"
32 .B "typedef struct { ...\& } pool;"
35 .B "\h'4n'pool_resource *next;"
36 .BI "\h'4n'void (*destroy)(pool_resource *" r );
44 .BI "void pool_init(pool *" p ", arena *" a );
45 .BI "pool *pool_create(arena *" a );
46 .BI "pool *pool_sub(pool *" p );
47 .BI "void pool_destroy(pool *" p );
48 .BI "void pool_add(pool *" p ", pool_resource *" r ,
49 .BI " void (*" dfn ")(pool_resource *" r ));
50 .BI "void *pool_alloc(pool *" p ", size_t " sz );
51 .BI "char *pool_strdup(pool *" p ", const char *" s );
52 .BI "pool_file *pool_fopen(pool *" p ", const char *" file ", const char *" how );
53 .BI "int pool_fclose(pool_file *" pf );
54 .BI "subarena *pool_subarena(pool *" p );
56 .BI "void POOL_ADD(pool *" p ", pool_resource *" r ,
57 .BI " void (*" dfn ")(pool_resource *" r ));
63 is a collection of resources (e.g., memory, files) which may be disposed
68 in which case it stands on its own, or it may be a
70 of another pool (which may in turn either be a root pool or a subpool of
73 Pools manage memory efficiently. Memory is allocated in large chunks
76 and given out as necessary to callers. There is no way of freeing
77 memory dynamically; instead, the memory allocated by a pool is freed
78 when the pool is destroyed. While allocation is rapid, there is waste
79 because the allocator has to ensure that blocks are properly aligned.
80 Since pools offer an arena interface, it is possible to build a
82 over them. This also enables memory in the subarena to be reclaimed
83 when the pool is destroyed.
85 Other resources (e.g., file handles) may be added to the pool. The pool
86 will automatically release any resources it has when it's destroyed.
87 Attaching resources to an appropriate pool can therefore be a useful way
88 of avoiding memory leaks.
89 .SS "Creating and destroying pools"
90 A new root pool is created using
92 passing it an arena from which it can allocate large memory blocks.
93 Alternatively, you can allocate a
95 structure from somewhere and initialize it by passing its address and an
99 A subpool is created by calling
101 naming the parent pool.
103 Pools are destroyed by passing them to
107 are completely destroyed, since the memory containing the pool structure
108 is allocated from the pool itself. Subpools and pools allocated by the
109 caller and initialized by
111 on the other hand, are
112 allocated from a parent pool, and may be reused after being `destroyed'.
113 .SS "Memory allocation"
114 Memory is allocated from a pool by calling
116 passing it the pool and the size of memory requested. There is an
117 interface for copying strings,
119 since this is a common operation. Note that there is no
121 if this is important, either use the pool's arena
123 directly or create a subpool.
129 which can be passed to other components to cause them to use the pool
130 for memory allocation.
131 .SS "Other resources"
132 Pool resources have a header of type
134 with the structure shown in the synopsis. Resources are added to the
135 pool by passing a pointer to the pool, the resource block and a
136 destruction function to
139 If your resource is freed before the pool is destroyed, manually zero
142 field in the resource header to let the pool manager know not to free
145 It's usual to allocate the resource structures from the pool's arena so
146 that they're automatically freed when the pool is destroyed.
150 may be created for a particular pool by calling
152 The subarena and its contents will be freed automatically when the pool
155 Files may be opened and registered with a pool by
159 argument specifies which pool, and the
163 arguments are passed to the standard
165 function. The return value is a pointer to a
167 structure, containing a member
169 which is the actual file handle. Don't call
171 directly on the file handle: instead pass the whole structure to
173 which will ensure that it doesn't get closed twice by accident. It's
174 advisable to close files by hand, to prevent the process from running
175 out; it's just not a disaster if you forget by accident.
182 Mark Wooding, <mdw@distorted.org.uk>