00001 /* Licensed to the Apache Software Foundation (ASF) under one or more 00002 * contributor license agreements. See the NOTICE file distributed with 00003 * this work for additional information regarding copyright ownership. 00004 * The ASF licenses this file to You under the Apache License, Version 2.0 00005 * (the "License"); you may not use this file except in compliance with 00006 * the License. You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef APR_POOLS_H 00018 #define APR_POOLS_H 00019 00020 /** 00021 * @file apr_pools.h 00022 * @brief APR memory allocation 00023 * 00024 * Resource allocation routines... 00025 * 00026 * designed so that we don't have to keep track of EVERYTHING so that 00027 * it can be explicitly freed later (a fundamentally unsound strategy --- 00028 * particularly in the presence of die()). 00029 * 00030 * Instead, we maintain pools, and allocate items (both memory and I/O 00031 * handlers) from the pools --- currently there are two, one for per 00032 * transaction info, and one for config info. When a transaction is over, 00033 * we can delete everything in the per-transaction apr_pool_t without fear, 00034 * and without thinking too hard about it either. 00035 */ 00036 00037 #include "apr.h" 00038 #include "apr_errno.h" 00039 #include "apr_general.h" /* for APR_STRINGIFY */ 00040 #define APR_WANT_MEMFUNC /**< for no good reason? */ 00041 #include "apr_want.h" 00042 00043 #ifdef __cplusplus 00044 extern "C" { 00045 #endif 00046 00047 /** 00048 * @defgroup apr_pools Memory Pool Functions 00049 * @ingroup APR 00050 * @{ 00051 */ 00052 00053 /** The fundamental pool type */ 00054 typedef struct apr_pool_t apr_pool_t; 00055 00056 00057 /** 00058 * Declaration helper macro to construct apr_foo_pool_get()s. 00059 * 00060 * This standardized macro is used by opaque (APR) data types to return 00061 * the apr_pool_t that is associated with the data type. 00062 * 00063 * APR_POOL_DECLARE_ACCESSOR() is used in a header file to declare the 00064 * accessor function. A typical usage and result would be: 00065 * <pre> 00066 * APR_POOL_DECLARE_ACCESSOR(file); 00067 * becomes: 00068 * APR_DECLARE(apr_pool_t *) apr_file_pool_get(apr_file_t *ob); 00069 * </pre> 00070 * @remark Doxygen unwraps this macro (via doxygen.conf) to provide 00071 * actual help for each specific occurance of apr_foo_pool_get. 00072 * @remark the linkage is specified for APR. It would be possible to expand 00073 * the macros to support other linkages. 00074 */ 00075 #define APR_POOL_DECLARE_ACCESSOR(type) \ 00076 APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \ 00077 (const apr_##type##_t *the##type) 00078 00079 /** 00080 * Implementation helper macro to provide apr_foo_pool_get()s. 00081 * 00082 * In the implementation, the APR_POOL_IMPLEMENT_ACCESSOR() is used to 00083 * actually define the function. It assumes the field is named "pool". 00084 */ 00085 #define APR_POOL_IMPLEMENT_ACCESSOR(type) \ 00086 APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \ 00087 (const apr_##type##_t *the##type) \ 00088 { return the##type->pool; } 00089 00090 00091 /** 00092 * Pool debug levels 00093 * 00094 * <pre> 00095 * | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 00096 * --------------------------------- 00097 * | | | | | | | | x | General debug code enabled (useful in 00098 * combination with --with-efence). 00099 * 00100 * | | | | | | | x | | Verbose output on stderr (report 00101 * CREATE, CLEAR, DESTROY). 00102 * 00103 * | | | | x | | | | | Verbose output on stderr (report 00104 * PALLOC, PCALLOC). 00105 * 00106 * | | | | | | x | | | Lifetime checking. On each use of a 00107 * pool, check its lifetime. If the pool 00108 * is out of scope, abort(). 00109 * In combination with the verbose flag 00110 * above, it will output LIFE in such an 00111 * event prior to aborting. 00112 * 00113 * | | | | | x | | | | Pool owner checking. On each use of a 00114 * pool, check if the current thread is the 00115 * pools owner. If not, abort(). In 00116 * combination with the verbose flag above, 00117 * it will output OWNER in such an event 00118 * prior to aborting. Use the debug 00119 * function apr_pool_owner_set() to switch 00120 * a pools ownership. 00121 * 00122 * When no debug level was specified, assume general debug mode. 00123 * If level 0 was specified, debugging is switched off 00124 * </pre> 00125 */ 00126 #if defined(APR_POOL_DEBUG) 00127 /* If APR_POOL_DEBUG is blank, we get 1; if it is a number, we get -1. */ 00128 #if (APR_POOL_DEBUG - APR_POOL_DEBUG -1 == 1) 00129 #undef APR_POOL_DEBUG 00130 #define APR_POOL_DEBUG 1 00131 #endif 00132 #else 00133 #define APR_POOL_DEBUG 0 00134 #endif 00135 00136 /** the place in the code where the particular function was called */ 00137 #define APR_POOL__FILE_LINE__ __FILE__ ":" APR_STRINGIFY(__LINE__) 00138 00139 00140 00141 /** A function that is called when allocation fails. */ 00142 typedef int (*apr_abortfunc_t)(int retcode); 00143 00144 /* 00145 * APR memory structure manipulators (pools, tables, and arrays). 00146 */ 00147 00148 /* 00149 * Initialization 00150 */ 00151 00152 /** 00153 * Setup all of the internal structures required to use pools 00154 * @remark Programs do NOT need to call this directly. APR will call this 00155 * automatically from apr_initialize. 00156 * @internal 00157 */ 00158 APR_DECLARE(apr_status_t) apr_pool_initialize(void); 00159 00160 /** 00161 * Tear down all of the internal structures required to use pools 00162 * @remark Programs do NOT need to call this directly. APR will call this 00163 * automatically from apr_terminate. 00164 * @internal 00165 */ 00166 APR_DECLARE(void) apr_pool_terminate(void); 00167 00168 00169 /* 00170 * Pool creation/destruction 00171 */ 00172 00173 #include "apr_allocator.h" 00174 00175 /** 00176 * Create a new pool. 00177 * @param newpool The pool we have just created. 00178 * @param parent The parent pool. If this is NULL, the new pool is a root 00179 * pool. If it is non-NULL, the new pool will inherit all 00180 * of its parent pool's attributes, except the apr_pool_t will 00181 * be a sub-pool. 00182 * @param abort_fn A function to use if the pool cannot allocate more memory. 00183 * @param allocator The allocator to use with the new pool. If NULL the 00184 * allocator of the parent pool will be used. 00185 */ 00186 APR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool, 00187 apr_pool_t *parent, 00188 apr_abortfunc_t abort_fn, 00189 apr_allocator_t *allocator); 00190 00191 /** 00192 * Create a new pool. 00193 * @deprecated @see apr_pool_create_unmanaged_ex. 00194 */ 00195 APR_DECLARE(apr_status_t) apr_pool_create_core_ex(apr_pool_t **newpool, 00196 apr_abortfunc_t abort_fn, 00197 apr_allocator_t *allocator); 00198 00199 /** 00200 * Create a new unmanaged pool. 00201 * @param newpool The pool we have just created. 00202 * @param abort_fn A function to use if the pool cannot allocate more memory. 00203 * @param allocator The allocator to use with the new pool. If NULL a 00204 * new allocator will be crated with newpool as owner. 00205 * @remark An unmanaged pool is a special pool without a parent; it will 00206 * NOT be destroyed upon apr_terminate. It must be explicitly 00207 * destroyed by calling apr_pool_destroy, to prevent memory leaks. 00208 * Use of this function is discouraged, think twice about whether 00209 * you really really need it. 00210 */ 00211 APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex(apr_pool_t **newpool, 00212 apr_abortfunc_t abort_fn, 00213 apr_allocator_t *allocator); 00214 00215 /** 00216 * Debug version of apr_pool_create_ex. 00217 * @param newpool @see apr_pool_create. 00218 * @param parent @see apr_pool_create. 00219 * @param abort_fn @see apr_pool_create. 00220 * @param allocator @see apr_pool_create. 00221 * @param file_line Where the function is called from. 00222 * This is usually APR_POOL__FILE_LINE__. 00223 * @remark Only available when APR_POOL_DEBUG is defined. 00224 * Call this directly if you have you apr_pool_create_ex 00225 * calls in a wrapper function and wish to override 00226 * the file_line argument to reflect the caller of 00227 * your wrapper function. If you do not have 00228 * apr_pool_create_ex in a wrapper, trust the macro 00229 * and don't call apr_pool_create_ex_debug directly. 00230 */ 00231 APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool, 00232 apr_pool_t *parent, 00233 apr_abortfunc_t abort_fn, 00234 apr_allocator_t *allocator, 00235 const char *file_line); 00236 00237 #if APR_POOL_DEBUG 00238 #define apr_pool_create_ex(newpool, parent, abort_fn, allocator) \ 00239 apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \ 00240 APR_POOL__FILE_LINE__) 00241 #endif 00242 00243 /** 00244 * Debug version of apr_pool_create_core_ex. 00245 * @deprecated @see apr_pool_create_unmanaged_ex_debug. 00246 */ 00247 APR_DECLARE(apr_status_t) apr_pool_create_core_ex_debug(apr_pool_t **newpool, 00248 apr_abortfunc_t abort_fn, 00249 apr_allocator_t *allocator, 00250 const char *file_line); 00251 00252 /** 00253 * Debug version of apr_pool_create_unmanaged_ex. 00254 * @param newpool @see apr_pool_create_unmanaged. 00255 * @param abort_fn @see apr_pool_create_unmanaged. 00256 * @param allocator @see apr_pool_create_unmanaged. 00257 * @param file_line Where the function is called from. 00258 * This is usually APR_POOL__FILE_LINE__. 00259 * @remark Only available when APR_POOL_DEBUG is defined. 00260 * Call this directly if you have you apr_pool_create_unmanaged_ex 00261 * calls in a wrapper function and wish to override 00262 * the file_line argument to reflect the caller of 00263 * your wrapper function. If you do not have 00264 * apr_pool_create_core_ex in a wrapper, trust the macro 00265 * and don't call apr_pool_create_core_ex_debug directly. 00266 */ 00267 APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex_debug(apr_pool_t **newpool, 00268 apr_abortfunc_t abort_fn, 00269 apr_allocator_t *allocator, 00270 const char *file_line); 00271 00272 #if APR_POOL_DEBUG 00273 #define apr_pool_create_core_ex(newpool, abort_fn, allocator) \ 00274 apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \ 00275 APR_POOL__FILE_LINE__) 00276 00277 #define apr_pool_create_unmanaged_ex(newpool, abort_fn, allocator) \ 00278 apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \ 00279 APR_POOL__FILE_LINE__) 00280 00281 #endif 00282 00283 /** 00284 * Create a new pool. 00285 * @param newpool The pool we have just created. 00286 * @param parent The parent pool. If this is NULL, the new pool is a root 00287 * pool. If it is non-NULL, the new pool will inherit all 00288 * of its parent pool's attributes, except the apr_pool_t will 00289 * be a sub-pool. 00290 */ 00291 #if defined(DOXYGEN) 00292 APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool, 00293 apr_pool_t *parent); 00294 #else 00295 #if APR_POOL_DEBUG 00296 #define apr_pool_create(newpool, parent) \ 00297 apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \ 00298 APR_POOL__FILE_LINE__) 00299 #else 00300 #define apr_pool_create(newpool, parent) \ 00301 apr_pool_create_ex(newpool, parent, NULL, NULL) 00302 #endif 00303 #endif 00304 00305 /** 00306 * Create a new pool. 00307 * @param newpool The pool we have just created. 00308 */ 00309 #if defined(DOXYGEN) 00310 APR_DECLARE(apr_status_t) apr_pool_create_core(apr_pool_t **newpool); 00311 APR_DECLARE(apr_status_t) apr_pool_create_unmanaged(apr_pool_t **newpool); 00312 #else 00313 #if APR_POOL_DEBUG 00314 #define apr_pool_create_core(newpool) \ 00315 apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \ 00316 APR_POOL__FILE_LINE__) 00317 #define apr_pool_create_unmanaged(newpool) \ 00318 apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \ 00319 APR_POOL__FILE_LINE__) 00320 #else 00321 #define apr_pool_create_core(newpool) \ 00322 apr_pool_create_unmanaged_ex(newpool, NULL, NULL) 00323 #define apr_pool_create_unmanaged(newpool) \ 00324 apr_pool_create_unmanaged_ex(newpool, NULL, NULL) 00325 #endif 00326 #endif 00327 00328 /** 00329 * Find the pools allocator 00330 * @param pool The pool to get the allocator from. 00331 */ 00332 APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool); 00333 00334 /** 00335 * Clear all memory in the pool and run all the cleanups. This also destroys all 00336 * subpools. 00337 * @param p The pool to clear 00338 * @remark This does not actually free the memory, it just allows the pool 00339 * to re-use this memory for the next allocation. 00340 * @see apr_pool_destroy() 00341 */ 00342 APR_DECLARE(void) apr_pool_clear(apr_pool_t *p); 00343 00344 /** 00345 * Debug version of apr_pool_clear. 00346 * @param p See: apr_pool_clear. 00347 * @param file_line Where the function is called from. 00348 * This is usually APR_POOL__FILE_LINE__. 00349 * @remark Only available when APR_POOL_DEBUG is defined. 00350 * Call this directly if you have you apr_pool_clear 00351 * calls in a wrapper function and wish to override 00352 * the file_line argument to reflect the caller of 00353 * your wrapper function. If you do not have 00354 * apr_pool_clear in a wrapper, trust the macro 00355 * and don't call apr_pool_destroy_clear directly. 00356 */ 00357 APR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p, 00358 const char *file_line); 00359 00360 #if APR_POOL_DEBUG 00361 #define apr_pool_clear(p) \ 00362 apr_pool_clear_debug(p, APR_POOL__FILE_LINE__) 00363 #endif 00364 00365 /** 00366 * Destroy the pool. This takes similar action as apr_pool_clear() and then 00367 * frees all the memory. 00368 * @param p The pool to destroy 00369 * @remark This will actually free the memory 00370 */ 00371 APR_DECLARE(void) apr_pool_destroy(apr_pool_t *p); 00372 00373 /** 00374 * Debug version of apr_pool_destroy. 00375 * @param p See: apr_pool_destroy. 00376 * @param file_line Where the function is called from. 00377 * This is usually APR_POOL__FILE_LINE__. 00378 * @remark Only available when APR_POOL_DEBUG is defined. 00379 * Call this directly if you have you apr_pool_destroy 00380 * calls in a wrapper function and wish to override 00381 * the file_line argument to reflect the caller of 00382 * your wrapper function. If you do not have 00383 * apr_pool_destroy in a wrapper, trust the macro 00384 * and don't call apr_pool_destroy_debug directly. 00385 */ 00386 APR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p, 00387 const char *file_line); 00388 00389 #if APR_POOL_DEBUG 00390 #define apr_pool_destroy(p) \ 00391 apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__) 00392 #endif 00393 00394 00395 /* 00396 * Memory allocation 00397 */ 00398 00399 /** 00400 * Allocate a block of memory from a pool 00401 * @param p The pool to allocate from 00402 * @param size The amount of memory to allocate 00403 * @return The allocated memory 00404 */ 00405 APR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size); 00406 00407 /** 00408 * Debug version of apr_palloc 00409 * @param p See: apr_palloc 00410 * @param size See: apr_palloc 00411 * @param file_line Where the function is called from. 00412 * This is usually APR_POOL__FILE_LINE__. 00413 * @return See: apr_palloc 00414 */ 00415 APR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size, 00416 const char *file_line); 00417 00418 #if APR_POOL_DEBUG 00419 #define apr_palloc(p, size) \ 00420 apr_palloc_debug(p, size, APR_POOL__FILE_LINE__) 00421 #endif 00422 00423 /** 00424 * Allocate a block of memory from a pool and set all of the memory to 0 00425 * @param p The pool to allocate from 00426 * @param size The amount of memory to allocate 00427 * @return The allocated memory 00428 */ 00429 #if defined(DOXYGEN) 00430 APR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size); 00431 #elif !APR_POOL_DEBUG 00432 #define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size) 00433 #endif 00434 00435 /** 00436 * Debug version of apr_pcalloc 00437 * @param p See: apr_pcalloc 00438 * @param size See: apr_pcalloc 00439 * @param file_line Where the function is called from. 00440 * This is usually APR_POOL__FILE_LINE__. 00441 * @return See: apr_pcalloc 00442 */ 00443 APR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size, 00444 const char *file_line); 00445 00446 #if APR_POOL_DEBUG 00447 #define apr_pcalloc(p, size) \ 00448 apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__) 00449 #endif 00450 00451 00452 /* 00453 * Pool Properties 00454 */ 00455 00456 /** 00457 * Set the function to be called when an allocation failure occurs. 00458 * @remark If the program wants APR to exit on a memory allocation error, 00459 * then this function can be called to set the callback to use (for 00460 * performing cleanup and then exiting). If this function is not called, 00461 * then APR will return an error and expect the calling program to 00462 * deal with the error accordingly. 00463 */ 00464 APR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc, 00465 apr_pool_t *pool); 00466 00467 /** 00468 * Get the abort function associated with the specified pool. 00469 * @param pool The pool for retrieving the abort function. 00470 * @return The abort function for the given pool. 00471 */ 00472 APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool); 00473 00474 /** 00475 * Get the parent pool of the specified pool. 00476 * @param pool The pool for retrieving the parent pool. 00477 * @return The parent of the given pool. 00478 */ 00479 APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool); 00480 00481 /** 00482 * Determine if pool a is an ancestor of pool b. 00483 * @param a The pool to search 00484 * @param b The pool to search for 00485 * @return True if a is an ancestor of b, NULL is considered an ancestor 00486 * of all pools. 00487 * @remark if compiled with APR_POOL_DEBUG, this function will also 00488 * return true if A is a pool which has been guaranteed by the caller 00489 * (using apr_pool_join) to have a lifetime at least as long as some 00490 * ancestor of pool B. 00491 */ 00492 APR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b); 00493 00494 /** 00495 * Tag a pool (give it a name) 00496 * @param pool The pool to tag 00497 * @param tag The tag 00498 */ 00499 APR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag); 00500 00501 00502 /* 00503 * User data management 00504 */ 00505 00506 /** 00507 * Set the data associated with the current pool 00508 * @param data The user data associated with the pool. 00509 * @param key The key to use for association 00510 * @param cleanup The cleanup program to use to cleanup the data (NULL if none) 00511 * @param pool The current pool 00512 * @warning The data to be attached to the pool should have a life span 00513 * at least as long as the pool it is being attached to. 00514 * 00515 * Users of APR must take EXTREME care when choosing a key to 00516 * use for their data. It is possible to accidentally overwrite 00517 * data by choosing a key that another part of the program is using. 00518 * Therefore it is advised that steps are taken to ensure that unique 00519 * keys are used for all of the userdata objects in a particular pool 00520 * (the same key in two different pools or a pool and one of its 00521 * subpools is okay) at all times. Careful namespace prefixing of 00522 * key names is a typical way to help ensure this uniqueness. 00523 * 00524 */ 00525 APR_DECLARE(apr_status_t) apr_pool_userdata_set( 00526 const void *data, 00527 const char *key, 00528 apr_status_t (*cleanup)(void *), 00529 apr_pool_t *pool); 00530 00531 /** 00532 * Set the data associated with the current pool 00533 * @param data The user data associated with the pool. 00534 * @param key The key to use for association 00535 * @param cleanup The cleanup program to use to cleanup the data (NULL if none) 00536 * @param pool The current pool 00537 * @note same as apr_pool_userdata_set(), except that this version doesn't 00538 * make a copy of the key (this function is useful, for example, when 00539 * the key is a string literal) 00540 * @warning This should NOT be used if the key could change addresses by 00541 * any means between the apr_pool_userdata_setn() call and a 00542 * subsequent apr_pool_userdata_get() on that key, such as if a 00543 * static string is used as a userdata key in a DSO and the DSO could 00544 * be unloaded and reloaded between the _setn() and the _get(). You 00545 * MUST use apr_pool_userdata_set() in such cases. 00546 * @warning More generally, the key and the data to be attached to the 00547 * pool should have a life span at least as long as the pool itself. 00548 * 00549 */ 00550 APR_DECLARE(apr_status_t) apr_pool_userdata_setn( 00551 const void *data, 00552 const char *key, 00553 apr_status_t (*cleanup)(void *), 00554 apr_pool_t *pool); 00555 00556 /** 00557 * Return the data associated with the current pool. 00558 * @param data The user data associated with the pool. 00559 * @param key The key for the data to retrieve 00560 * @param pool The current pool. 00561 */ 00562 APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key, 00563 apr_pool_t *pool); 00564 00565 00566 /** 00567 * @defgroup PoolCleanup Pool Cleanup Functions 00568 * 00569 * Cleanups are performed in the reverse order they were registered. That is: 00570 * Last In, First Out. A cleanup function can safely allocate memory from 00571 * the pool that is being cleaned up. It can also safely register additional 00572 * cleanups which will be run LIFO, directly after the current cleanup 00573 * terminates. Cleanups have to take caution in calling functions that 00574 * create subpools. Subpools, created during cleanup will NOT automatically 00575 * be cleaned up. In other words, cleanups are to clean up after themselves. 00576 * 00577 * @{ 00578 */ 00579 00580 /** 00581 * Register a function to be called when a pool is cleared or destroyed 00582 * @param p The pool register the cleanup with 00583 * @param data The data to pass to the cleanup function. 00584 * @param plain_cleanup The function to call when the pool is cleared 00585 * or destroyed 00586 * @param child_cleanup The function to call when a child process is about 00587 * to exec - this function is called in the child, obviously! 00588 */ 00589 APR_DECLARE(void) apr_pool_cleanup_register( 00590 apr_pool_t *p, 00591 const void *data, 00592 apr_status_t (*plain_cleanup)(void *), 00593 apr_status_t (*child_cleanup)(void *)); 00594 00595 /** 00596 * Register a function to be called when a pool is cleared or destroyed. 00597 * 00598 * Unlike apr_pool_cleanup_register which register a cleanup 00599 * that is called AFTER all subpools are destroyed this function register 00600 * a function that will be called before any of the subpool is destoryed. 00601 * 00602 * @param p The pool register the cleanup with 00603 * @param data The data to pass to the cleanup function. 00604 * @param plain_cleanup The function to call when the pool is cleared 00605 * or destroyed 00606 */ 00607 APR_DECLARE(void) apr_pool_pre_cleanup_register( 00608 apr_pool_t *p, 00609 const void *data, 00610 apr_status_t (*plain_cleanup)(void *)); 00611 00612 /** 00613 * Remove a previously registered cleanup function. 00614 * 00615 * The cleanup most recently registered with @a p having the same values of 00616 * @a data and @a cleanup will be removed. 00617 * 00618 * @param p The pool to remove the cleanup from 00619 * @param data The data of the registered cleanup 00620 * @param cleanup The function to remove from cleanup 00621 * @remarks For some strange reason only the plain_cleanup is handled by this 00622 * function 00623 */ 00624 APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data, 00625 apr_status_t (*cleanup)(void *)); 00626 00627 /** 00628 * Replace the child cleanup function of a previously registered cleanup. 00629 * 00630 * The cleanup most recently registered with @a p having the same values of 00631 * @a data and @a plain_cleanup will have the registered child cleanup 00632 * function replaced with @a child_cleanup. 00633 * 00634 * @param p The pool of the registered cleanup 00635 * @param data The data of the registered cleanup 00636 * @param plain_cleanup The plain cleanup function of the registered cleanup 00637 * @param child_cleanup The function to register as the child cleanup 00638 */ 00639 APR_DECLARE(void) apr_pool_child_cleanup_set( 00640 apr_pool_t *p, 00641 const void *data, 00642 apr_status_t (*plain_cleanup)(void *), 00643 apr_status_t (*child_cleanup)(void *)); 00644 00645 /** 00646 * Run the specified cleanup function immediately and unregister it. 00647 * 00648 * The cleanup most recently registered with @a p having the same values of 00649 * @a data and @a cleanup will be removed and @a cleanup will be called 00650 * with @a data as the argument. 00651 * 00652 * @param p The pool to remove the cleanup from 00653 * @param data The data to remove from cleanup 00654 * @param cleanup The function to remove from cleanup 00655 */ 00656 APR_DECLARE(apr_status_t) apr_pool_cleanup_run( 00657 apr_pool_t *p, 00658 void *data, 00659 apr_status_t (*cleanup)(void *)); 00660 00661 /** 00662 * An empty cleanup function. 00663 * 00664 * Passed to apr_pool_cleanup_register() when no cleanup is required. 00665 * 00666 * @param data The data to cleanup, will not be used by this function. 00667 */ 00668 APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data); 00669 00670 /** 00671 * Run all registered child cleanups, in preparation for an exec() 00672 * call in a forked child -- close files, etc., but *don't* flush I/O 00673 * buffers, *don't* wait for subprocesses, and *don't* free any 00674 * memory. 00675 */ 00676 APR_DECLARE(void) apr_pool_cleanup_for_exec(void); 00677 00678 /** @} */ 00679 00680 /** 00681 * @defgroup PoolDebug Pool Debugging functions. 00682 * 00683 * pools have nested lifetimes -- sub_pools are destroyed when the 00684 * parent pool is cleared. We allow certain liberties with operations 00685 * on things such as tables (and on other structures in a more general 00686 * sense) where we allow the caller to insert values into a table which 00687 * were not allocated from the table's pool. The table's data will 00688 * remain valid as long as all the pools from which its values are 00689 * allocated remain valid. 00690 * 00691 * For example, if B is a sub pool of A, and you build a table T in 00692 * pool B, then it's safe to insert data allocated in A or B into T 00693 * (because B lives at most as long as A does, and T is destroyed when 00694 * B is cleared/destroyed). On the other hand, if S is a table in 00695 * pool A, it is safe to insert data allocated in A into S, but it 00696 * is *not safe* to insert data allocated from B into S... because 00697 * B can be cleared/destroyed before A is (which would leave dangling 00698 * pointers in T's data structures). 00699 * 00700 * In general we say that it is safe to insert data into a table T 00701 * if the data is allocated in any ancestor of T's pool. This is the 00702 * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor 00703 * relationships for all data inserted into tables. APR_POOL_DEBUG also 00704 * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other 00705 * folks to implement similar restrictions for their own data 00706 * structures. 00707 * 00708 * However, sometimes this ancestor requirement is inconvenient -- 00709 * sometimes it's necessary to create a sub pool where the sub pool is 00710 * guaranteed to have the same lifetime as the parent pool. This is a 00711 * guarantee implemented by the *caller*, not by the pool code. That 00712 * is, the caller guarantees they won't destroy the sub pool 00713 * individually prior to destroying the parent pool. 00714 * 00715 * In this case the caller must call apr_pool_join() to indicate this 00716 * guarantee to the APR_POOL_DEBUG code. 00717 * 00718 * These functions are only implemented when #APR_POOL_DEBUG is set. 00719 * 00720 * @{ 00721 */ 00722 #if APR_POOL_DEBUG || defined(DOXYGEN) 00723 /** 00724 * Guarantee that a subpool has the same lifetime as the parent. 00725 * @param p The parent pool 00726 * @param sub The subpool 00727 */ 00728 APR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub); 00729 00730 /** 00731 * Find a pool from something allocated in it. 00732 * @param mem The thing allocated in the pool 00733 * @return The pool it is allocated in 00734 */ 00735 APR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem); 00736 00737 /** 00738 * Report the number of bytes currently in the pool 00739 * @param p The pool to inspect 00740 * @param recurse Recurse/include the subpools' sizes 00741 * @return The number of bytes 00742 */ 00743 APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse); 00744 00745 /** 00746 * Lock a pool 00747 * @param pool The pool to lock 00748 * @param flag The flag 00749 */ 00750 APR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag); 00751 00752 /* @} */ 00753 00754 #else /* APR_POOL_DEBUG or DOXYGEN */ 00755 00756 #ifdef apr_pool_join 00757 #undef apr_pool_join 00758 #endif 00759 #define apr_pool_join(a,b) 00760 00761 #ifdef apr_pool_lock 00762 #undef apr_pool_lock 00763 #endif 00764 #define apr_pool_lock(pool, lock) 00765 00766 #endif /* APR_POOL_DEBUG or DOXYGEN */ 00767 00768 /** @} */ 00769 00770 #ifdef __cplusplus 00771 } 00772 #endif 00773 00774 #endif /* !APR_POOLS_H */