Main Page | Data Structures | File List | Globals

include/pool.h

00001 /* An Apache-like pool allocator.
00002  * By Richard W.M. Jones <rich@annexia.org>
00003  *
00004  * This library is free software; you can redistribute it and/or
00005  * modify it under the terms of the GNU Library General Public
00006  * License as published by the Free Software Foundation; either
00007  * version 2 of the License, or (at your option) any later version.
00008  *
00009  * This library is distributed in the hope that it will be useful,
00010  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00011  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00012  * Library General Public License for more details.
00013  *
00014  * You should have received a copy of the GNU Library General Public
00015  * License along with this library; if not, write to the Free
00016  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00017  *
00018  * $Id: pool.h,v 1.2 2004/01/26 17:54:53 chappell Exp $
00019  */
00020 
00021 #ifndef POOL_H
00022 #define POOL_H
00023 
00024 #include <stdlib.h>
00025 
00026 struct pool;
00027 typedef struct pool *pool;
00028 
00029 /* Function: new_pool - allocate a new pool
00030  *
00031  * Allocate a new pool. Pools must eventually be deleted explicitly
00032  * by calling @ref{delete_pool(3)}.
00033  *
00034  * Note that @code{new_pool} is now deprecated. It is almost always
00035  * better to create a subpool of the global pool, ie:
00036  *
00037  * @code{pool = new_subpool (global_pool);}
00038  *
00039  * This has the distinct advantage that your new pool will be cleaned
00040  * up properly if the process calls @code{exit}.
00041  *
00042  * See also: @ref{new_subpool(3)}, @ref{global_pool(3)},
00043  * @ref{delete_pool(3)}.
00044  */
00045 extern pool new_pool (void);
00046 
00047 /* Function: new_subpool - allocate a subpool of an existing pool
00048  *
00049  * Allocate a new subpool. The pool may either be deleted explicitly, or
00050  * else is deleted implicitly when the parent pool is deleted.
00051  */
00052 extern pool new_subpool (pool);
00053 
00054 /* Function: delete_pool - delete a pool
00055  *
00056  * Delete a pool or subpool. This also deletes any subpools that the
00057  * pool may own (and recursively subpools of those subpools, etc.)
00058  */
00059 extern void delete_pool (pool);
00060 
00061 /* Function: c2_pmalloc - allocate memory in a pool
00062  * Function: c2_pcalloc
00063  * Function: c2_prealloc
00064  *
00065  * Allocate memory in a pool or, if pool is null, on the main heap
00066  * (equivalent to plain @code{malloc}). If memory is allocated in a real
00067  * pool, then it is automatically freed when the pool is deleted.
00068  *
00069  * Memory returned is word-aligned.
00070  *
00071  * If a memory allocation fails, the @code{bad_malloc_handler} function is
00072  * called (which defaults to just calling @ref{abort(3)}).
00073  *
00074  * @code{c2_pcalloc} is identical to @code{c2_pmalloc} but also sets the memory
00075  * to zero before returning it.
00076  *
00077  * @code{c2_prealloc} increases the size of an existing memory allocation.
00078  * @code{c2_prealloc} might move the memory in the process of reallocating it.
00079  *
00080  * Bugs: @code{c2_prealloc} cannot reduce the size of an existing memory
00081  * allocation.
00082  */
00083 extern void *c2_pmalloc (pool, size_t n);
00084 extern void *c2_pcalloc (pool, size_t nmemb, size_t size);
00085 extern void *c2_prealloc (pool, void *ptr, size_t n);
00086 
00087 /* Function: pool_register_malloc - allow pool to own malloc'd memory
00088  *
00089  * Register an anonymous area of malloc-allocated memory which
00090  * will be freed (with @ref{free(3)}) when the pool is deleted.
00091  */
00092 extern void pool_register_malloc (pool, void *ptr);
00093 
00094 /* Function: pool_register_fd - allow pool to own file descriptor
00095  *
00096  * Register a file descriptor to be closed when the pool is deleted.
00097  * There is no way to unregister a file descriptor. If you wish to
00098  * do that, then you probably want to register the fd in a subpool.
00099  */
00100 extern void pool_register_fd (pool, int fd);
00101 
00102 /* Function: pool_register_cleanup_fn - call function when pool is deleted
00103  *
00104  * Register a function to be called when the pool is deleted. There
00105  * is no way to unregister this function. If you wish to do that, then
00106  * you probably want to register it in a subpool.
00107  */
00108 extern void pool_register_cleanup_fn (pool, void (*fn) (void *), void *data);
00109 
00110 /* Function: pool_set_bad_malloc_handler - set handler for when malloc fails
00111  *
00112  * Set the function which is called when an underlying malloc or realloc
00113  * operation fails. The default is that @ref{abort(3)} is called.
00114  *
00115  * This function returns the previous handler.
00116  */
00117 extern void (*pool_set_bad_malloc_handler (void (*fn) (void))) (void);
00118 
00119 struct pool_stats
00120 {
00121   int nr_subpools;
00122   int struct_size;
00123 };
00124 
00125 /* Function: pool_get_stats - get statistics from the pool
00126  *
00127  * Return various statistics collected for the pool. This function
00128  * fills in the @code{stats} argument which should point to a
00129  * structure of type @code{struct pool_stats}. @code{n} should be
00130  * set to the size of this structure.
00131  *
00132  * @code{struct pool_stats} currently contains the following fields:
00133  *
00134  * @code{nr_subpools}: The number of subpools (including the current pool).
00135  *
00136  * @code{struct_size}: The memory overhead used by the pool allocator
00137  * itself to store structures. This includes subpools.
00138  */
00139 extern void pool_get_stats (const pool, struct pool_stats *stats, size_t n);
00140 
00141 /* Obsolete calls for backwards compatibility. These will be removed soon. */
00142 #define pool_get_size(p) (-1)
00143 #define pool_get_areas(p) (-1)
00144 #define pool_get_allocations(p) (-1)
00145 #define pool_nr_subpools(p) (-1)
00146 
00147 #ifndef NO_GLOBAL_POOL
00148 /* Variable: global_pool - the global pool for global allocations
00149  *
00150  * This is the global pool which is allocated before @code{main()} is called
00151  * and deleted automatically upon program exit. Items allocated on this
00152  * pool cannot be deleted until the program ends, and so it is a good
00153  * idea not to allocate short-lived items here.
00154  */
00155 extern pool global_pool;
00156 #endif /* !NO_GLOBAL_POOL */
00157 
00158 #endif /* POOL_H */

Generated on Fri Feb 20 15:17:48 2004 for PPR Libraries by doxygen 1.3.5