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