chiark - git - mdw - mLib/blob - mem/pool.3.in

   1 .\" -*-nroff-*-
   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"
  32 .\" @pool_alloc
  33 .\" @pool_strdup
  34 .\" @pool_init
  35 .\" @pool_create
  36 .\" @pool_destroy
  37 .\" @pool_sub
  38 .\" @pool_add
  39 .\" @POOL_ADD
  40 .\" @pool_fopen
  41 .\" @pool_fclose
  42 .\" @pool_subarena
  43 .
  44 .\"--------------------------------------------------------------------------
  45 .SH "NAME"
  46 pool \- resource pool management
  47 .
  48 .\"--------------------------------------------------------------------------
  49 .SH "SYNOPSIS"
  50 .
  51 .nf
  52 .B "#include <mLib/pool.h>"
  53 .PP
  54 .B "typedef struct { ...\& } pool;"
  55 .PP
  56 .ta 2n
  57 .B "typedef struct {"
  58 .B "    pool_resource *next;"
  59 .BI "   void (*destroy)(pool_resource *" r );
  60 .B "} pool_resource;"
  61 .PP
  62 .B "typedef struct {"
  63 .B "    FILE *fp;"
  64 .B "    ..."
  65 .B "} pool_file;"
  66 .PP
  67 .BI "void pool_init(pool *" p ", arena *" a );
  68 .BI "pool *pool_create(arena *" a );
  69 .BI "pool *pool_sub(pool *" p );
  70 .BI "void pool_destroy(pool *" p );
  71 .ta \w'\fBvoid pool_add('u
  72 .BI "void pool_add(pool *" p ", pool_resource *" r ,
  73 .BI "   void (*" dfn ")(pool_resource *" r ));
  74 .BI "void *pool_alloc(pool *" p ", size_t " sz );
  75 .BI "char *pool_strdup(pool *" p ", const char *" s );
  76 .BI "pool_file *pool_fopen(pool *" p ", const char *" file ", const char *" how );
  77 .BI "int pool_fclose(pool_file *" pf );
  78 .BI "subarena *pool_subarena(pool *" p );
  79 .PP
  80 .ta \w'\fBvoid POOL_ADD('u
  81 .BI "void POOL_ADD(pool *" p ", pool_resource *" r ,
  82 .BI "   void (*" dfn ")(pool_resource *" r ));
  83 .fi
  84 .
  85 .\"--------------------------------------------------------------------------
  86 .SH "DESCRIPTION"
  87 .
  88 .SS "Overview"
  89 A
  90 .I "resource pool"
  91 is a collection of resources (e.g., memory, files) which may be disposed
  92 of simultaneously.
  93 .PP
  94 A pool may be a
  95 .IR "root pool" ,
  96 in which case it stands on its own, or it may be a
  97 .IR "subpool"
  98 of another pool (which may in turn either be a root pool or a subpool of
  99 another).
 100 .PP
 101 Pools manage memory efficiently.  Memory is allocated in large chunks
 102 from an
 103 .BR arena (3),
 104 and given out as necessary to callers.  There is no way of freeing
 105 memory dynamically; instead, the memory allocated by a pool is freed
 106 when the pool is destroyed.  While allocation is rapid, there is waste
 107 because the allocator has to ensure that blocks are properly aligned.
 108 Since pools offer an arena interface, it is possible to build a
 109 .BR subarena (3)
 110 over them.  This also enables memory in the subarena to be reclaimed
 111 when the pool is destroyed.
 112 .PP
 113 Other resources (e.g., file handles) may be added to the pool.  The pool
 114 will automatically release any resources it has when it's destroyed.
 115 Attaching resources to an appropriate pool can therefore be a useful way
 116 of avoiding memory leaks.
 117 .
 118 .SS "Creating and destroying pools"
 119 A new root pool is created using
 120 .BR pool_create ,
 121 passing it an arena from which it can allocate large memory blocks.
 122 Alternatively, you can allocate a
 123 .B pool
 124 structure from somewhere and initialize it by passing its address and an
 125 arena to
 126 .BR pool_init .
 127 .PP
 128 A subpool is created by calling
 129 .BR pool_sub ,
 130 naming the parent pool.
 131 .PP
 132 Pools are destroyed by passing them to
 133 .BR pool_destroy .
 134 Pools created by
 135 .B pool_create
 136 are completely destroyed, since the memory containing the pool structure
 137 is allocated from the pool itself.  Subpools and pools allocated by the
 138 caller and initialized by
 139 .BR pool_init ,
 140 on the other hand, are
 141 allocated from a parent pool, and may be reused after being `destroyed'.
 142 .
 143 .SS "Memory allocation"
 144 Memory is allocated from a pool by calling
 145 .BR pool_alloc ,
 146 passing it the pool and the size of memory requested.  There is an
 147 interface for copying strings,
 148 .BR pool_strdup ,
 149 since this is a common operation.  Note that there is no
 150 .BR pool_free :
 151 if this is important, either use the pool's arena
 152 .B p->pa
 153 directly or create a subpool.
 154 .PP
 155 A pool provides an
 156 .BR arena (3)
 157 interface,
 158 .BR p->a ,
 159 which can be passed to other components to cause them to use the pool
 160 for memory allocation.
 161 .
 162 .SS "Other resources"
 163 Pool resources have a header of type
 164 .B pool_resource
 165 with the structure shown in the synopsis.  Resources are added to the
 166 pool by passing a pointer to the pool, the resource block and a
 167 destruction function to
 168 .BR pool_add .
 169 .PP
 170 If your resource is freed before the pool is destroyed, manually zero
 171 the
 172 .B destroy
 173 field in the resource header to let the pool manager know not to free
 174 the resource again.
 175 .PP
 176 It's usual to allocate the resource structures from the pool's arena so
 177 that they're automatically freed when the pool is destroyed.
 178 .PP
 179 A
 180 .BR subarena (3)
 181 may be created for a particular pool by calling
 182 .BR pool_subarena .
 183 The subarena and its contents will be freed automatically when the pool
 184 is destroyed.
 185 .PP
 186 Files may be opened and registered with a pool by
 187 .BR pool_fopen :
 188 the
 189 .I pool
 190 argument specifies which pool, and the
 191 .I file
 192 and
 193 .I how
 194 arguments are passed to the standard
 195 .BR fopen (3)
 196 function.  The return value is a pointer to a
 197 .B pool_file
 198 structure, containing a member
 199 .B fp
 200 which is the actual file handle.  Don't call
 201 .B fclose
 202 directly on the file handle: instead pass the whole structure to
 203 .B pool_fclose
 204 which will ensure that it doesn't get closed twice by accident.  It's
 205 advisable to close files by hand, to prevent the process from running
 206 out; it's just not a disaster if you forget by accident.
 207 .
 208 .\"--------------------------------------------------------------------------
 209 .SH "SEE ALSO"
 210 .
 211 .BR alloc (3),
 212 .BR arena (3),
 213 .BR mLib (3),
 214 .BR sub (3).
 215 .
 216 .\"--------------------------------------------------------------------------
 217 .SH AUTHOR
 218 .
 219 Mark Wooding, <mdw@distorted.org.uk>
 220 .
 221 .\"----- That's all, folks --------------------------------------------------