14 .TH pool 3 "7 July 2000" mLib
16 pool \- resource pool management
29 .B "#include <mLib/pool.h>"
31 .BI "pool *pool_create(arena *" a );
32 .BI "pool *pool_sub(pool *" p );
33 .BI "void pool_destroy(pool *" p );
34 .BI "void pool_add(pool *" p ", pool_resource *" r ,
35 .BI " void (*" dfn ")(pool_resource *" r ));
36 .BI "void *pool_alloc(pool *" p ", size_t " sz );
37 .BI "char *pool_strdup(pool *" p ", const char *" s );
38 .BI "pool_file *pool_fopen(pool *" p ", const char *" file ", const char *" how );
39 .BI "int pool_fclose(pool_file *" pf );
40 .BI "subarena *pool_subarena(pool *" p );
42 .BI "void POOL_ADD(pool *" p ", pool_resource *" r ,
43 .BI " void (*" dfn ")(pool_resource *" r ));
49 is a collection of resources (e.g., memory, files) which may be disposed
54 in which case it stands on its own, or it may be a
56 of another pool (which may in turn either be a root pool or a subpool of
59 Pools manage memory efficiently. Memory is allocated in large chunks
62 and given out as necessary to callers. There is no way of freeing
63 memory dynamically; instead, the memory allocated by a pool is freed
64 when the pool is destroyed. While allocation is rapid, there is waste
65 because the allocator has to ensure that blocks are properly aligned.
66 Since pools offer an arena interface, it is possible to build a
68 over them. This also enables memory in the subarena to be reclaimed
69 when the pool is destroyed.
71 Other resources (e.g., file handles) may be added to the pool. The pool
72 will automatically release any resources it has when it's destroyed.
73 Attaching resources to an appropriate pool can therefore be a useful way
74 of avoiding memory leaks.
75 .SS "Creating and destroying pools"
76 A new root pool is created using
78 passing it an arena from which it can allocate large memory blocks.
80 A subpool is created by calling
82 naming the parent pool.
84 Pools are destroyed by passing them to
86 Root pools are completely destroyed, since the memory containing the
87 pool structure is allocated from the pool itself. Subpools, on the
88 other hand, are allocated from a parent pool, and may be reused after
90 .SS "Memory allocation"
91 Memory is allocated from a pool by calling
93 passing it the pool and the size of memory requested. There is an
94 interface for copying strings,
96 since this is a common operation. Note that there is no
98 if this is important, either use the pool's arena
100 directly or create a subpool.
106 which can be passed to other components to cause them to use the pool
107 for memory allocation.
108 .SS "Other resources"
109 Pool resources have a header of type
113 typedef struct pool_resource {
114 struct pool_resource *next;
115 void (*destroy)(struct pool_resource */*r*/);
118 Resources are added to the pool by passing a pointer to the pool, the
119 resource block and a destruction function to
122 If your resource is freed before the pool is destroyed, manually zero
125 field in the resource header to let the pool manager know not to free
128 It's usual to allocate the resource structures from the pool's arena so
129 that they're automatically freed when the pool is destroyed.
133 may be created for a particular pool by calling
135 The subarena and its contents will be freed automatically when the pool
138 Files may be opened and registered with a pool by
142 argument specifies which pool, and the
146 arguments are passed to the standard
148 function. The return value is a pointer to a
150 structure, containing a member
152 which is the actual file handle. Don't call
154 directly on the file handle: instead pass the whole structure to
156 which will ensure that it doesn't get closed twice by accident. It's
157 advisable to close files by hand, to prevent the process from running
158 out; it's just not a disaster if you forget by accident.
165 Mark Wooding, <mdw@nsict.org>