mdw@git.distorted.org.uk Git - 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_create
  35 .\" @pool_destroy
  36 .\" @pool_sub
  37 .\" @pool_add
  38 .\" @POOL_ADD
  39 .\" @pool_fopen
  40 .\" @pool_fclose
  41 .\" @pool_subarena
  42 .
  43 .\"--------------------------------------------------------------------------
  44 .SH "NAME"
  45 pool \- resource pool management
  46 .
  47 .\"--------------------------------------------------------------------------
  48 .SH "SYNOPSIS"
  49 .
  50 .nf
  51 .B "#include <mLib/pool.h>"
  52 .PP
  53 .B "typedef struct { ...\& } pool;"
  54 .PP
  55 .ta 2n
  56 .B "typedef struct {"
  57 .B "    pool_resource *next;"
  58 .BI "   void (*destroy)(pool_resource *" r );
  59 .B "} pool_resource;"
  60 .PP
  61 .B "typedef struct {"
  62 .B "    FILE *fp;"
  63 .B "    ..."
  64 .B "} pool_file;"
  65 .PP
  66 .BI "pool *pool_create(arena *" a );
  67 .BI "pool *pool_sub(pool *" p );
  68 .BI "void pool_destroy(pool *" p );
  69 .ta \w'\fBvoid pool_add('u
  70 .BI "void pool_add(pool *" p ", pool_resource *" r ,
  71 .BI "   void (*" dfn ")(pool_resource *" r ));
  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 );
  77 .PP
  78 .ta \w'\fBvoid POOL_ADD('u
  79 .BI "void POOL_ADD(pool *" p ", pool_resource *" r ,
  80 .BI "   void (*" dfn ")(pool_resource *" r ));
  81 .fi
  82 .
  83 .\"--------------------------------------------------------------------------
  84 .SH "DESCRIPTION"
  85 .
  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
  95 .IR "subpool"
  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.
 115 .
 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 .
 127 Pools created by
 128 .B pool_create
 129 are completely destroyed, since the memory containing the pool structure
 130 is allocated from the pool itself.  Subpools, on the other hand, are
 131 allocated from a parent pool, and may be reused after being `destroyed'.
 132 .
 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.
 151 .
 152 .SS "Other resources"
 153 Pool resources have a header of type
 154 .B pool_resource
 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
 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.
 197 .
 198 .\"--------------------------------------------------------------------------
 199 .SH "SEE ALSO"
 200 .
 201 .BR alloc (3),
 202 .BR arena (3),
 203 .BR mLib (3),
 204 .BR sub (3).
 205 .
 206 .\"--------------------------------------------------------------------------
 207 .SH AUTHOR
 208 .
 209 Mark Wooding, <mdw@distorted.org.uk>
 210 .
 211 .\"----- That's all, folks --------------------------------------------------