chiark / gitweb /
Document the `pool' interface.
[mLib] / man / pool.3
9787c8a8 1.\" -*-nroff-*- VS
3.sp 1
6.ft B
7.. VE
9.ft R
12.sp 1
14.TH pool 3 "7 July 2000" mLib
15.SH "NAME"
16pool \- resource pool management
17.\" @pool_alloc
18.\" @pool_strdup
19.\" @pool_create
20.\" @pool_destroy
21.\" @pool_sub
22.\" @pool_add
23.\" @POOL_ADD
24.\" @pool_fopen
25.\" @pool_fclose
26.\" @pool_subarena
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 ));
46.SS "Overview"
48.I "resource pool"
49is a collection of resources (e.g., memory, files) which may be disposed
50of simultaneously.
52A pool may be a
53.IR "root pool" ,
54in which case it stands on its own, or it may be a
55.IR "subpool"
56of another pool (which may in turn either be a root pool or a subpool of
59Pools manage memory efficiently. Memory is allocated in large chunks
60from an
61.BR arena (3),
62and given out as necessary to callers. There is no way of freeing
63memory dynamically; instead, the memory allocated by a pool is freed
64when the pool is destroyed. While allocation is rapid, there is waste
65because the allocator has to ensure that blocks are properly aligned.
66Since pools offer an arena interface, it is possible to build a
67.BR subarena (3)
68over them. This also enables memory in the subarena to be reclaimed
69when the pool is destroyed.
71Other resources (e.g., file handles) may be added to the pool. The pool
72will automatically release any resources it has when it's destroyed.
73Attaching resources to an appropriate pool can therefore be a useful way
74of avoiding memory leaks.
75.SS "Creating and destroying pools"
76A new root pool is created using
77.BR pool_create ,
78passing it an arena from which it can allocate large memory blocks.
80A subpool is created by calling
81.BR pool_sub ,
82naming the parent pool.
84Pools are destroyed by passing them to
85.BR pool_destroy .
86Root pools are completely destroyed, since the memory containing the
87pool structure is allocated from the pool itself. Subpools, on the
88other hand, are allocated from a parent pool, and may be reused after
89being `destroyed'.
90.SS "Memory allocation"
91Memory is allocated from a pool by calling
92.BR pool_alloc ,
93passing it the pool and the size of memory requested. There is an
94interface for copying strings,
95.BR pool_strdup ,
96since this is a common operation. Note that there is no
97.BR pool_free :
98if this is important, either use the pool's arena
99.B p->pa
100directly or create a subpool.
102A pool provides an
103.BR arena (3)
105.BR p->a ,
106which can be passed to other components to cause them to use the pool
107for memory allocation.
108.SS "Other resources"
109Pool resources have a header of type
110.B pool_resource
111with the structure:
113typedef struct pool_resource {
114 struct pool_resource *next;
115 void (*destroy)(struct pool_resource */*r*/);
116} pool_resource;
118Resources are added to the pool by passing a pointer to the pool, the
119resource block and a destruction function to
120.BR pool_add .
122If your resource is freed before the pool is destroyed, manually zero
124.B destroy
125field in the resource header to let the pool manager know not to free
126the resource again.
128It's usual to allocate the resource structures from the pool's arena so
129that they're automatically freed when the pool is destroyed.
132.BR subarena (3)
133may be created for a particular pool by calling
134.BR pool_subarena .
135The subarena and its contents will be freed automatically when the pool
136is destroyed.
138Files may be opened and registered with a pool by
139.BR pool_fopen :
141.I pool
142argument specifies which pool, and the
143.I file
145.I how
146arguments are passed to the standard
147.BR fopen (3)
148function. The return value is a pointer to a
149.B pool_file
150structure, containing a member
151.B fp
152which is the actual file handle. Don't call
153.B fclose
154directly on the file handle: instead pass the whole structure to
155.B pool_fclose
156which will ensure that it doesn't get closed twice by accident. It's
157advisable to close files by hand, to prevent the process from running
158out; it's just not a disaster if you forget by accident.
160.BR alloc (3),
161.BR arena (3),
162.BR mLib (3),
163.BR subarena (3).
165Mark Wooding, <>