pool.h

   1 /* An Apache-like pool allocator.
   2  * By Richard W.M. Jones <rich@annexia.org>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the Free
  16  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17  *
  18  * $Id: pool.h,v 1.7 2002/06/08 11:50:44 rich Exp $
  19  */
  20
  21 #ifndef POOL_H
  22 #define POOL_H
  23
  24 #include <stdlib.h>
  25
  26 struct pool;
  27 typedef struct pool *pool;
  28
  29 /* Function: new_pool - allocate a new pool
  30  *
  31  * Allocate a new pool. Pools must eventually be deleted explicitly
  32  * by calling @ref{delete_pool(3)}.
  33  *
  34  * Note that @code{new_pool} is now deprecated. It is almost always
  35  * better to create a subpool of the global pool, ie:
  36  *
  37  * @code{pool = new_subpool (global_pool);}
  38  *
  39  * This has the distinct advantage that your new pool will be cleaned
  40  * up properly if the process calls @code{exit}.
  41  *
  42  * See also: @ref{new_subpool(3)}, @ref{global_pool(3)},
  43  * @ref{delete_pool(3)}.
  44  */
  45 extern pool new_pool (void);
  46
  47 /* Function: new_subpool - allocate a subpool of an existing pool
  48  *
  49  * Allocate a new subpool. The pool may either be deleted explicitly, or
  50  * else is deleted implicitly when the parent pool is deleted.
  51  */
  52 extern pool new_subpool (pool);
  53
  54 /* Function: delete_pool - delete a pool
  55  *
  56  * Delete a pool or subpool. This also deletes any subpools that the
  57  * pool may own (and recursively subpools of those subpools, etc.)
  58  */
  59 extern void delete_pool (pool);
  60
  61 /* Function: pmalloc - allocate memory in a pool
  62  * Function: pcalloc
  63  * Function: prealloc
  64  *
  65  * Allocate memory in a pool or, if pool is null, on the main heap
  66  * (equivalent to plain @code{malloc}). If memory is allocated in a real
  67  * pool, then it is automatically freed when the pool is deleted.
  68  *
  69  * Memory returned is word-aligned.
  70  *
  71  * If a memory allocation fails, the @code{bad_malloc_handler} function is
  72  * called (which defaults to just calling @ref{abort(3)}).
  73  *
  74  * @code{pcalloc} is identical to @code{pmalloc} but also sets the memory
  75  * to zero before returning it.
  76  *
  77  * @code{prealloc} increases the size of an existing memory allocation.
  78  * @code{prealloc} might move the memory in the process of reallocating it.
  79  *
  80  * Bugs: @code{prealloc} cannot reduce the size of an existing memory
  81  * allocation.
  82  */
  83 extern void *pmalloc (pool, size_t n);
  84 extern void *pcalloc (pool, size_t nmemb, size_t size);
  85 extern void *prealloc (pool, void *ptr, size_t n);
  86
  87 /* Function: pool_register_malloc - allow pool to own malloc'd memory
  88  *
  89  * Register an anonymous area of malloc-allocated memory which
  90  * will be freed (with @ref{free(3)}) when the pool is deleted.
  91  */
  92 extern void pool_register_malloc (pool, void *ptr);
  93
  94 /* Function: pool_register_fd - allow pool to own file descriptor
  95  *
  96  * Register a file descriptor to be closed when the pool is deleted.
  97  * There is no way to unregister a file descriptor. If you wish to
  98  * do that, then you probably want to register the fd in a subpool.
  99  */
 100 extern void pool_register_fd (pool, int fd);
 101
 102 /* Function: pool_register_cleanup_fn - call function when pool is deleted
 103  *
 104  * Register a function to be called when the pool is deleted. There
 105  * is no way to unregister this function. If you wish to do that, then
 106  * you probably want to register it in a subpool.
 107  */
 108 extern void pool_register_cleanup_fn (pool, void (*fn) (void *), void *data);
 109
 110 /* Function: pool_set_bad_malloc_handler - set handler for when malloc fails
 111  *
 112  * Set the function which is called when an underlying malloc or realloc
 113  * operation fails. The default is that @ref{abort(3)} is called.
 114  *
 115  * This function returns the previous handler.
 116  */
 117 extern void (*pool_set_bad_malloc_handler (void (*fn) (void))) (void);
 118
 119 struct pool_stats
 120 {
 121   int nr_subpools;
 122   int struct_size;
 123 };
 124
 125 /* Function: pool_get_stats - get statistics from the pool
 126  *
 127  * Return various statistics collected for the pool. This function
 128  * fills in the @code{stats} argument which should point to a
 129  * structure of type @code{struct pool_stats}. @code{n} should be
 130  * set to the size of this structure.
 131  *
 132  * @code{struct pool_stats} currently contains the following fields:
 133  *
 134  * @code{nr_subpools}: The number of subpools (including the current pool).
 135  *
 136  * @code{struct_size}: The memory overhead used by the pool allocator
 137  * itself to store structures. This includes subpools.
 138  */
 139 extern void pool_get_stats (const pool, struct pool_stats *stats, size_t n);
 140
 141 /* Obsolete calls for backwards compatibility. These will be removed soon. */
 142 #define pool_get_size(p) (-1)
 143 #define pool_get_areas(p) (-1)
 144 #define pool_get_allocations(p) (-1)
 145 #define pool_nr_subpools(p) (-1)
 146
 147 #ifndef NO_GLOBAL_POOL
 148 /* Variable: global_pool - the global pool for global allocations
 149  *
 150  * This is the global pool which is allocated before @code{main()} is called
 151  * and deleted automatically upon program exit. Items allocated on this
 152  * pool cannot be deleted until the program ends, and so it is a good
 153  * idea not to allocate short-lived items here.
 154  */
 155 extern pool global_pool;
 156 #endif /* !NO_GLOBAL_POOL */
 157
 158 #endif /* POOL_H */