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 */