Commit | Line | Data |
---|---|---|
9787c8a8 | 1 | .\" -*-nroff-*- |
c4ccbbf9 MW |
2 | .\" |
3 | .\" Manual for resource pools | |
4 | .\" | |
5 | .\" (c) 2000, 2001, 2003, 2005, 2007, 2009, 2023, 2024 Straylight/Edgeware | |
6 | .\" | |
7 | . | |
8 | .\"----- Licensing notice --------------------------------------------------- | |
9 | .\" | |
10 | .\" This file is part of the mLib utilities library. | |
11 | .\" | |
12 | .\" mLib is free software: you can redistribute it and/or modify it under | |
13 | .\" the terms of the GNU Library General Public License as published by | |
14 | .\" the Free Software Foundation; either version 2 of the License, or (at | |
15 | .\" your option) any later version. | |
16 | .\" | |
17 | .\" mLib is distributed in the hope that it will be useful, but WITHOUT | |
18 | .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
19 | .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public | |
20 | .\" License for more details. | |
21 | .\" | |
22 | .\" You should have received a copy of the GNU Library General Public | |
23 | .\" License along with mLib. If not, write to the Free Software | |
24 | .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, | |
25 | .\" USA. | |
26 | . | |
27 | .\"-------------------------------------------------------------------------- | |
28 | .so ../defs.man \" @@@PRE@@@ | |
29 | . | |
30 | .\"-------------------------------------------------------------------------- | |
31 | .TH pool 3mLib "7 July 2000" "Straylight/Edgeware" "mLib utilities library" | |
9787c8a8 | 32 | .\" @pool_alloc |
33 | .\" @pool_strdup | |
34 | .\" @pool_create | |
35 | .\" @pool_destroy | |
36 | .\" @pool_sub | |
37 | .\" @pool_add | |
38 | .\" @POOL_ADD | |
39 | .\" @pool_fopen | |
40 | .\" @pool_fclose | |
41 | .\" @pool_subarena | |
c4ccbbf9 MW |
42 | . |
43 | .\"-------------------------------------------------------------------------- | |
44 | .SH "NAME" | |
45 | pool \- resource pool management | |
46 | . | |
47 | .\"-------------------------------------------------------------------------- | |
9787c8a8 | 48 | .SH "SYNOPSIS" |
c4ccbbf9 | 49 | . |
9787c8a8 | 50 | .nf |
51 | .B "#include <mLib/pool.h>" | |
d056fbdf | 52 | .PP |
4729aa69 | 53 | .B "typedef struct { ...\& } pool;" |
d056fbdf | 54 | .PP |
adec5584 | 55 | .ta 2n |
4729aa69 | 56 | .B "typedef struct {" |
adec5584 MW |
57 | .B " pool_resource *next;" |
58 | .BI " void (*destroy)(pool_resource *" r ); | |
4729aa69 | 59 | .B "} pool_resource;" |
d056fbdf | 60 | .PP |
4729aa69 | 61 | .B "typedef struct {" |
adec5584 MW |
62 | .B " FILE *fp;" |
63 | .B " ..." | |
4729aa69 | 64 | .B "} pool_file;" |
d056fbdf | 65 | .PP |
9787c8a8 | 66 | .BI "pool *pool_create(arena *" a ); |
67 | .BI "pool *pool_sub(pool *" p ); | |
68 | .BI "void pool_destroy(pool *" p ); | |
adec5584 | 69 | .ta \w'\fBvoid pool_add('u |
9787c8a8 | 70 | .BI "void pool_add(pool *" p ", pool_resource *" r , |
adec5584 | 71 | .BI " void (*" dfn ")(pool_resource *" r )); |
9787c8a8 | 72 | .BI "void *pool_alloc(pool *" p ", size_t " sz ); |
73 | .BI "char *pool_strdup(pool *" p ", const char *" s ); | |
74 | .BI "pool_file *pool_fopen(pool *" p ", const char *" file ", const char *" how ); | |
75 | .BI "int pool_fclose(pool_file *" pf ); | |
76 | .BI "subarena *pool_subarena(pool *" p ); | |
d056fbdf | 77 | .PP |
adec5584 | 78 | .ta \w'\fBvoid POOL_ADD('u |
9787c8a8 | 79 | .BI "void POOL_ADD(pool *" p ", pool_resource *" r , |
adec5584 | 80 | .BI " void (*" dfn ")(pool_resource *" r )); |
9787c8a8 | 81 | .fi |
c4ccbbf9 MW |
82 | . |
83 | .\"-------------------------------------------------------------------------- | |
9787c8a8 | 84 | .SH "DESCRIPTION" |
c4ccbbf9 | 85 | . |
9787c8a8 | 86 | .SS "Overview" |
87 | A | |
88 | .I "resource pool" | |
89 | is a collection of resources (e.g., memory, files) which may be disposed | |
90 | of simultaneously. | |
91 | .PP | |
92 | A pool may be a | |
93 | .IR "root pool" , | |
94 | in which case it stands on its own, or it may be a | |
d4efbcd9 | 95 | .IR "subpool" |
9787c8a8 | 96 | of another pool (which may in turn either be a root pool or a subpool of |
97 | another). | |
98 | .PP | |
99 | Pools manage memory efficiently. Memory is allocated in large chunks | |
100 | from an | |
101 | .BR arena (3), | |
102 | and given out as necessary to callers. There is no way of freeing | |
103 | memory dynamically; instead, the memory allocated by a pool is freed | |
104 | when the pool is destroyed. While allocation is rapid, there is waste | |
105 | because the allocator has to ensure that blocks are properly aligned. | |
106 | Since pools offer an arena interface, it is possible to build a | |
107 | .BR subarena (3) | |
108 | over them. This also enables memory in the subarena to be reclaimed | |
109 | when the pool is destroyed. | |
110 | .PP | |
111 | Other resources (e.g., file handles) may be added to the pool. The pool | |
112 | will automatically release any resources it has when it's destroyed. | |
113 | Attaching resources to an appropriate pool can therefore be a useful way | |
114 | of avoiding memory leaks. | |
c4ccbbf9 | 115 | . |
9787c8a8 | 116 | .SS "Creating and destroying pools" |
117 | A new root pool is created using | |
118 | .BR pool_create , | |
119 | passing it an arena from which it can allocate large memory blocks. | |
120 | .PP | |
121 | A subpool is created by calling | |
122 | .BR pool_sub , | |
123 | naming the parent pool. | |
124 | .PP | |
125 | Pools are destroyed by passing them to | |
126 | .BR pool_destroy . | |
c5775f49 | 127 | Pools created by |
128 | .B pool_create | |
129 | are completely destroyed, since the memory containing the pool structure | |
b1a20bee | 130 | is allocated from the pool itself. Subpools, on the other hand, are |
c5775f49 | 131 | allocated from a parent pool, and may be reused after being `destroyed'. |
c4ccbbf9 | 132 | . |
9787c8a8 | 133 | .SS "Memory allocation" |
134 | Memory is allocated from a pool by calling | |
135 | .BR pool_alloc , | |
136 | passing it the pool and the size of memory requested. There is an | |
137 | interface for copying strings, | |
138 | .BR pool_strdup , | |
139 | since this is a common operation. Note that there is no | |
140 | .BR pool_free : | |
141 | if this is important, either use the pool's arena | |
142 | .B p->pa | |
143 | directly or create a subpool. | |
144 | .PP | |
145 | A pool provides an | |
146 | .BR arena (3) | |
147 | interface, | |
148 | .BR p->a , | |
149 | which can be passed to other components to cause them to use the pool | |
150 | for memory allocation. | |
c4ccbbf9 | 151 | . |
9787c8a8 | 152 | .SS "Other resources" |
153 | Pool resources have a header of type | |
154 | .B pool_resource | |
4729aa69 MW |
155 | with the structure shown in the synopsis. Resources are added to the |
156 | pool by passing a pointer to the pool, the resource block and a | |
157 | destruction function to | |
9787c8a8 | 158 | .BR pool_add . |
159 | .PP | |
160 | If your resource is freed before the pool is destroyed, manually zero | |
161 | the | |
162 | .B destroy | |
163 | field in the resource header to let the pool manager know not to free | |
164 | the resource again. | |
165 | .PP | |
166 | It's usual to allocate the resource structures from the pool's arena so | |
167 | that they're automatically freed when the pool is destroyed. | |
168 | .PP | |
169 | A | |
170 | .BR subarena (3) | |
171 | may be created for a particular pool by calling | |
172 | .BR pool_subarena . | |
173 | The subarena and its contents will be freed automatically when the pool | |
174 | is destroyed. | |
175 | .PP | |
176 | Files may be opened and registered with a pool by | |
177 | .BR pool_fopen : | |
178 | the | |
179 | .I pool | |
180 | argument specifies which pool, and the | |
181 | .I file | |
182 | and | |
183 | .I how | |
184 | arguments are passed to the standard | |
185 | .BR fopen (3) | |
186 | function. The return value is a pointer to a | |
187 | .B pool_file | |
188 | structure, containing a member | |
189 | .B fp | |
190 | which is the actual file handle. Don't call | |
191 | .B fclose | |
192 | directly on the file handle: instead pass the whole structure to | |
193 | .B pool_fclose | |
194 | which will ensure that it doesn't get closed twice by accident. It's | |
195 | advisable to close files by hand, to prevent the process from running | |
196 | out; it's just not a disaster if you forget by accident. | |
c4ccbbf9 MW |
197 | . |
198 | .\"-------------------------------------------------------------------------- | |
9787c8a8 | 199 | .SH "SEE ALSO" |
c4ccbbf9 | 200 | . |
9787c8a8 | 201 | .BR alloc (3), |
202 | .BR arena (3), | |
203 | .BR mLib (3), | |
c4ccbbf9 MW |
204 | .BR sub (3). |
205 | . | |
206 | .\"-------------------------------------------------------------------------- | |
9787c8a8 | 207 | .SH AUTHOR |
c4ccbbf9 | 208 | . |
9b5ac6ff | 209 | Mark Wooding, <mdw@distorted.org.uk> |
c4ccbbf9 MW |
210 | . |
211 | .\"----- That's all, folks -------------------------------------------------- |