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 * @param newpool The pool we have just created. 00194 * @param abort_fn A function to use if the pool cannot allocate more memory. 00195 * @param allocator The allocator to use with the new pool. If NULL the 00196 * new allocator will be crated with newpool as owner. 00197 */ 00198 APR_DECLARE(apr_status_t) apr_pool_create_core_ex(apr_pool_t **newpool, 00199 apr_abortfunc_t abort_fn, 00200 apr_allocator_t *allocator); 00201 00202 /** 00203 * Debug version of apr_pool_create_ex. 00204 * @param newpool @see apr_pool_create. 00205 * @param parent @see apr_pool_create. 00206 * @param abort_fn @see apr_pool_create. 00207 * @param allocator @see apr_pool_create. 00208 * @param file_line Where the function is called from. 00209 * This is usually APR_POOL__FILE_LINE__. 00210 * @remark Only available when APR_POOL_DEBUG is defined. 00211 * Call this directly if you have you apr_pool_create_ex 00212 * calls in a wrapper function and wish to override 00213 * the file_line argument to reflect the caller of 00214 * your wrapper function. If you do not have 00215 * apr_pool_create_ex in a wrapper, trust the macro 00216 * and don't call apr_pool_create_ex_debug directly. 00217 */ 00218 APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool, 00219 apr_pool_t *parent, 00220 apr_abortfunc_t abort_fn, 00221 apr_allocator_t *allocator, 00222 const char *file_line); 00223 00224 #if APR_POOL_DEBUG 00225 #define apr_pool_create_ex(newpool, parent, abort_fn, allocator) \ 00226 apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \ 00227 APR_POOL__FILE_LINE__) 00228 #endif 00229 00230 /** 00231 * Debug version of apr_pool_create_core_ex. 00232 * @param newpool @see apr_pool_create. 00233 * @param abort_fn @see apr_pool_create. 00234 * @param allocator @see apr_pool_create. 00235 * @param file_line Where the function is called from. 00236 * This is usually APR_POOL__FILE_LINE__. 00237 * @remark Only available when APR_POOL_DEBUG is defined. 00238 * Call this directly if you have you apr_pool_create_core_ex 00239 * calls in a wrapper function and wish to override 00240 * the file_line argument to reflect the caller of 00241 * your wrapper function. If you do not have 00242 * apr_pool_create_core_ex in a wrapper, trust the macro 00243 * and don't call apr_pool_create_core_ex_debug directly. 00244 */ 00245 APR_DECLARE(apr_status_t) apr_pool_create_core_ex_debug(apr_pool_t **newpool, 00246 apr_abortfunc_t abort_fn, 00247 apr_allocator_t *allocator, 00248 const char *file_line); 00249 00250 #if APR_POOL_DEBUG 00251 #define apr_pool_create_core_ex(newpool, abort_fn, allocator) \ 00252 apr_pool_create_core_ex_debug(newpool, abort_fn, allocator, \ 00253 APR_POOL__FILE_LINE__) 00254 #endif 00255 00256 /** 00257 * Create a new pool. 00258 * @param newpool The pool we have just created. 00259 * @param parent The parent pool. If this is NULL, the new pool is a root 00260 * pool. If it is non-NULL, the new pool will inherit all 00261 * of its parent pool's attributes, except the apr_pool_t will 00262 * be a sub-pool. 00263 */ 00264 #if defined(DOXYGEN) 00265 APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool, 00266 apr_pool_t *parent); 00267 #else 00268 #if APR_POOL_DEBUG 00269 #define apr_pool_create(newpool, parent) \ 00270 apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \ 00271 APR_POOL__FILE_LINE__) 00272 #else 00273 #define apr_pool_create(newpool, parent) \ 00274 apr_pool_create_ex(newpool, parent, NULL, NULL) 00275 #endif 00276 #endif 00277 00278 /** 00279 * Create a new pool. 00280 * @param newpool The pool we have just created. 00281 */ 00282 #if defined(DOXYGEN) 00283 APR_DECLARE(apr_status_t) apr_pool_create_core(apr_pool_t **newpool); 00284 #else 00285 #if APR_POOL_DEBUG 00286 #define apr_pool_create_core(newpool) \ 00287 apr_pool_create_core_ex_debug(newpool, NULL, NULL, \ 00288 APR_POOL__FILE_LINE__) 00289 #else 00290 #define apr_pool_create_core(newpool) \ 00291 apr_pool_create_core_ex(newpool, NULL, NULL) 00292 #endif 00293 #endif 00294 00295 /** 00296 * Find the pools allocator 00297 * @param pool The pool to get the allocator from. 00298 */ 00299 APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool); 00300 00301 /** 00302 * Clear all memory in the pool and run all the cleanups. This also destroys all 00303 * subpools. 00304 * @param p The pool to clear 00305 * @remark This does not actually free the memory, it just allows the pool 00306 * to re-use this memory for the next allocation. 00307 * @see apr_pool_destroy() 00308 */ 00309 APR_DECLARE(void) apr_pool_clear(apr_pool_t *p); 00310 00311 /** 00312 * Debug version of apr_pool_clear. 00313 * @param p See: apr_pool_clear. 00314 * @param file_line Where the function is called from. 00315 * This is usually APR_POOL__FILE_LINE__. 00316 * @remark Only available when APR_POOL_DEBUG is defined. 00317 * Call this directly if you have you apr_pool_clear 00318 * calls in a wrapper function and wish to override 00319 * the file_line argument to reflect the caller of 00320 * your wrapper function. If you do not have 00321 * apr_pool_clear in a wrapper, trust the macro 00322 * and don't call apr_pool_destroy_clear directly. 00323 */ 00324 APR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p, 00325 const char *file_line); 00326 00327 #if APR_POOL_DEBUG 00328 #define apr_pool_clear(p) \ 00329 apr_pool_clear_debug(p, APR_POOL__FILE_LINE__) 00330 #endif 00331 00332 /** 00333 * Destroy the pool. This takes similar action as apr_pool_clear() and then 00334 * frees all the memory. 00335 * @param p The pool to destroy 00336 * @remark This will actually free the memory 00337 */ 00338 APR_DECLARE(void) apr_pool_destroy(apr_pool_t *p); 00339 00340 /** 00341 * Debug version of apr_pool_destroy. 00342 * @param p See: apr_pool_destroy. 00343 * @param file_line Where the function is called from. 00344 * This is usually APR_POOL__FILE_LINE__. 00345 * @remark Only available when APR_POOL_DEBUG is defined. 00346 * Call this directly if you have you apr_pool_destroy 00347 * calls in a wrapper function and wish to override 00348 * the file_line argument to reflect the caller of 00349 * your wrapper function. If you do not have 00350 * apr_pool_destroy in a wrapper, trust the macro 00351 * and don't call apr_pool_destroy_debug directly. 00352 */ 00353 APR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p, 00354 const char *file_line); 00355 00356 #if APR_POOL_DEBUG 00357 #define apr_pool_destroy(p) \ 00358 apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__) 00359 #endif 00360 00361 00362 /* 00363 * Memory allocation 00364 */ 00365 00366 /** 00367 * Allocate a block of memory from a pool 00368 * @param p The pool to allocate from 00369 * @param size The amount of memory to allocate 00370 * @return The allocated memory 00371 */ 00372 APR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size); 00373 00374 /** 00375 * Debug version of apr_palloc 00376 * @param p See: apr_palloc 00377 * @param size See: apr_palloc 00378 * @param file_line Where the function is called from. 00379 * This is usually APR_POOL__FILE_LINE__. 00380 * @return See: apr_palloc 00381 */ 00382 APR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size, 00383 const char *file_line); 00384 00385 #if APR_POOL_DEBUG 00386 #define apr_palloc(p, size) \ 00387 apr_palloc_debug(p, size, APR_POOL__FILE_LINE__) 00388 #endif 00389 00390 /** 00391 * Allocate a block of memory from a pool and set all of the memory to 0 00392 * @param p The pool to allocate from 00393 * @param size The amount of memory to allocate 00394 * @return The allocated memory 00395 */ 00396 #if defined(DOXYGEN) 00397 APR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size); 00398 #elif !APR_POOL_DEBUG 00399 #define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size) 00400 #endif 00401 00402 /** 00403 * Debug version of apr_pcalloc 00404 * @param p See: apr_pcalloc 00405 * @param size See: apr_pcalloc 00406 * @param file_line Where the function is called from. 00407 * This is usually APR_POOL__FILE_LINE__. 00408 * @return See: apr_pcalloc 00409 */ 00410 APR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size, 00411 const char *file_line); 00412 00413 #if APR_POOL_DEBUG 00414 #define apr_pcalloc(p, size) \ 00415 apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__) 00416 #endif 00417 00418 00419 /* 00420 * Pool Properties 00421 */ 00422 00423 /** 00424 * Set the function to be called when an allocation failure occurs. 00425 * @remark If the program wants APR to exit on a memory allocation error, 00426 * then this function can be called to set the callback to use (for 00427 * performing cleanup and then exiting). If this function is not called, 00428 * then APR will return an error and expect the calling program to 00429 * deal with the error accordingly. 00430 */ 00431 APR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc, 00432 apr_pool_t *pool); 00433 00434 /** 00435 * Get the abort function associated with the specified pool. 00436 * @param pool The pool for retrieving the abort function. 00437 * @return The abort function for the given pool. 00438 */ 00439 APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool); 00440 00441 /** 00442 * Get the parent pool of the specified pool. 00443 * @param pool The pool for retrieving the parent pool. 00444 * @return The parent of the given pool. 00445 */ 00446 APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool); 00447 00448 /** 00449 * Determine if pool a is an ancestor of pool b. 00450 * @param a The pool to search 00451 * @param b The pool to search for 00452 * @return True if a is an ancestor of b, NULL is considered an ancestor 00453 * of all pools. 00454 * @remark if compiled with APR_POOL_DEBUG, this function will also 00455 * return true if A is a pool which has been guaranteed by the caller 00456 * (using apr_pool_join) to have a lifetime at least as long as some 00457 * ancestor of pool B. 00458 */ 00459 APR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b); 00460 00461 /** 00462 * Tag a pool (give it a name) 00463 * @param pool The pool to tag 00464 * @param tag The tag 00465 */ 00466 APR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag); 00467 00468 00469 /* 00470 * User data management 00471 */ 00472 00473 /** 00474 * Set the data associated with the current pool 00475 * @param data The user data associated with the pool. 00476 * @param key The key to use for association 00477 * @param cleanup The cleanup program to use to cleanup the data (NULL if none) 00478 * @param pool The current pool 00479 * @warning The data to be attached to the pool should have a life span 00480 * at least as long as the pool it is being attached to. 00481 * 00482 * Users of APR must take EXTREME care when choosing a key to 00483 * use for their data. It is possible to accidentally overwrite 00484 * data by choosing a key that another part of the program is using. 00485 * Therefore it is advised that steps are taken to ensure that unique 00486 * keys are used for all of the userdata objects in a particular pool 00487 * (the same key in two different pools or a pool and one of its 00488 * subpools is okay) at all times. Careful namespace prefixing of 00489 * key names is a typical way to help ensure this uniqueness. 00490 * 00491 */ 00492 APR_DECLARE(apr_status_t) apr_pool_userdata_set( 00493 const void *data, 00494 const char *key, 00495 apr_status_t (*cleanup)(void *), 00496 apr_pool_t *pool); 00497 00498 /** 00499 * Set the data associated with the current pool 00500 * @param data The user data associated with the pool. 00501 * @param key The key to use for association 00502 * @param cleanup The cleanup program to use to cleanup the data (NULL if none) 00503 * @param pool The current pool 00504 * @note same as apr_pool_userdata_set(), except that this version doesn't 00505 * make a copy of the key (this function is useful, for example, when 00506 * the key is a string literal) 00507 * @warning This should NOT be used if the key could change addresses by 00508 * any means between the apr_pool_userdata_setn() call and a 00509 * subsequent apr_pool_userdata_get() on that key, such as if a 00510 * static string is used as a userdata key in a DSO and the DSO could 00511 * be unloaded and reloaded between the _setn() and the _get(). You 00512 * MUST use apr_pool_userdata_set() in such cases. 00513 * @warning More generally, the key and the data to be attached to the 00514 * pool should have a life span at least as long as the pool itself. 00515 * 00516 */ 00517 APR_DECLARE(apr_status_t) apr_pool_userdata_setn( 00518 const void *data, 00519 const char *key, 00520 apr_status_t (*cleanup)(void *), 00521 apr_pool_t *pool); 00522 00523 /** 00524 * Return the data associated with the current pool. 00525 * @param data The user data associated with the pool. 00526 * @param key The key for the data to retrieve 00527 * @param pool The current pool. 00528 */ 00529 APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key, 00530 apr_pool_t *pool); 00531 00532 00533 /** 00534 * @defgroup PoolCleanup Pool Cleanup Functions 00535 * 00536 * Cleanups are performed in the reverse order they were registered. That is: 00537 * Last In, First Out. A cleanup function can safely allocate memory from 00538 * the pool that is being cleaned up. It can also safely register additional 00539 * cleanups which will be run LIFO, directly after the current cleanup 00540 * terminates. Cleanups have to take caution in calling functions that 00541 * create subpools. Subpools, created during cleanup will NOT automatically 00542 * be cleaned up. In other words, cleanups are to clean up after themselves. 00543 * 00544 * @{ 00545 */ 00546 00547 /** 00548 * Register a function to be called when a pool is cleared or destroyed 00549 * @param p The pool register the cleanup with 00550 * @param data The data to pass to the cleanup function. 00551 * @param plain_cleanup The function to call when the pool is cleared 00552 * or destroyed 00553 * @param child_cleanup The function to call when a child process is about 00554 * to exec - this function is called in the child, obviously! 00555 */ 00556 APR_DECLARE(void) apr_pool_cleanup_register( 00557 apr_pool_t *p, 00558 const void *data, 00559 apr_status_t (*plain_cleanup)(void *), 00560 apr_status_t (*child_cleanup)(void *)); 00561 00562 /** 00563 * Register a function to be called when a pool is cleared or destroyed. 00564 * 00565 * Unlike apr_pool_cleanup_register which register a cleanup 00566 * that is called AFTER all subpools are destroyed this function register 00567 * a function that will be called before any of the subpool is destoryed. 00568 * 00569 * @param p The pool register the cleanup with 00570 * @param data The data to pass to the cleanup function. 00571 * @param plain_cleanup The function to call when the pool is cleared 00572 * or destroyed 00573 */ 00574 APR_DECLARE(void) apr_pool_pre_cleanup_register( 00575 apr_pool_t *p, 00576 const void *data, 00577 apr_status_t (*plain_cleanup)(void *)); 00578 00579 /** 00580 * Remove a previously registered cleanup function. 00581 * 00582 * The cleanup most recently registered with @a p having the same values of 00583 * @a data and @a cleanup will be removed. 00584 * 00585 * @param p The pool to remove the cleanup from 00586 * @param data The data of the registered cleanup 00587 * @param cleanup The function to remove from cleanup 00588 * @remarks For some strange reason only the plain_cleanup is handled by this 00589 * function 00590 */ 00591 APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data, 00592 apr_status_t (*cleanup)(void *)); 00593 00594 /** 00595 * Replace the child cleanup function of a previously registered cleanup. 00596 * 00597 * The cleanup most recently registered with @a p having the same values of 00598 * @a data and @a plain_cleanup will have the registered child cleanup 00599 * function replaced with @a child_cleanup. 00600 * 00601 * @param p The pool of the registered cleanup 00602 * @param data The data of the registered cleanup 00603 * @param plain_cleanup The plain cleanup function of the registered cleanup 00604 * @param child_cleanup The function to register as the child cleanup 00605 */ 00606 APR_DECLARE(void) apr_pool_child_cleanup_set( 00607 apr_pool_t *p, 00608 const void *data, 00609 apr_status_t (*plain_cleanup)(void *), 00610 apr_status_t (*child_cleanup)(void *)); 00611 00612 /** 00613 * Run the specified cleanup function immediately and unregister it. 00614 * 00615 * The cleanup most recently registered with @a p having the same values of 00616 * @a data and @a cleanup will be removed and @a cleanup will be called 00617 * with @a data as the argument. 00618 * 00619 * @param p The pool to remove the cleanup from 00620 * @param data The data to remove from cleanup 00621 * @param cleanup The function to remove from cleanup 00622 */ 00623 APR_DECLARE(apr_status_t) apr_pool_cleanup_run( 00624 apr_pool_t *p, 00625 void *data, 00626 apr_status_t (*cleanup)(void *)); 00627 00628 /** 00629 * An empty cleanup function. 00630 * 00631 * Passed to apr_pool_cleanup_register() when no cleanup is required. 00632 * 00633 * @param data The data to cleanup, will not be used by this function. 00634 */ 00635 APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data); 00636 00637 /** 00638 * Run all registered child cleanups, in preparation for an exec() 00639 * call in a forked child -- close files, etc., but *don't* flush I/O 00640 * buffers, *don't* wait for subprocesses, and *don't* free any 00641 * memory. 00642 */ 00643 APR_DECLARE(void) apr_pool_cleanup_for_exec(void); 00644 00645 /** @} */ 00646 00647 /** 00648 * @defgroup PoolDebug Pool Debugging functions. 00649 * 00650 * pools have nested lifetimes -- sub_pools are destroyed when the 00651 * parent pool is cleared. We allow certain liberties with operations 00652 * on things such as tables (and on other structures in a more general 00653 * sense) where we allow the caller to insert values into a table which 00654 * were not allocated from the table's pool. The table's data will 00655 * remain valid as long as all the pools from which its values are 00656 * allocated remain valid. 00657 * 00658 * For example, if B is a sub pool of A, and you build a table T in 00659 * pool B, then it's safe to insert data allocated in A or B into T 00660 * (because B lives at most as long as A does, and T is destroyed when 00661 * B is cleared/destroyed). On the other hand, if S is a table in 00662 * pool A, it is safe to insert data allocated in A into S, but it 00663 * is *not safe* to insert data allocated from B into S... because 00664 * B can be cleared/destroyed before A is (which would leave dangling 00665 * pointers in T's data structures). 00666 * 00667 * In general we say that it is safe to insert data into a table T 00668 * if the data is allocated in any ancestor of T's pool. This is the 00669 * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor 00670 * relationships for all data inserted into tables. APR_POOL_DEBUG also 00671 * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other 00672 * folks to implement similar restrictions for their own data 00673 * structures. 00674 * 00675 * However, sometimes this ancestor requirement is inconvenient -- 00676 * sometimes it's necessary to create a sub pool where the sub pool is 00677 * guaranteed to have the same lifetime as the parent pool. This is a 00678 * guarantee implemented by the *caller*, not by the pool code. That 00679 * is, the caller guarantees they won't destroy the sub pool 00680 * individually prior to destroying the parent pool. 00681 * 00682 * In this case the caller must call apr_pool_join() to indicate this 00683 * guarantee to the APR_POOL_DEBUG code. 00684 * 00685 * These functions are only implemented when #APR_POOL_DEBUG is set. 00686 * 00687 * @{ 00688 */ 00689 #if APR_POOL_DEBUG || defined(DOXYGEN) 00690 /** 00691 * Guarantee that a subpool has the same lifetime as the parent. 00692 * @param p The parent pool 00693 * @param sub The subpool 00694 */ 00695 APR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub); 00696 00697 /** 00698 * Find a pool from something allocated in it. 00699 * @param mem The thing allocated in the pool 00700 * @return The pool it is allocated in 00701 */ 00702 APR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem); 00703 00704 /** 00705 * Report the number of bytes currently in the pool 00706 * @param p The pool to inspect 00707 * @param recurse Recurse/include the subpools' sizes 00708 * @return The number of bytes 00709 */ 00710 APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse); 00711 00712 /** 00713 * Lock a pool 00714 * @param pool The pool to lock 00715 * @param flag The flag 00716 */ 00717 APR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag); 00718 00719 /* @} */ 00720 00721 #else /* APR_POOL_DEBUG or DOXYGEN */ 00722 00723 #ifdef apr_pool_join 00724 #undef apr_pool_join 00725 #endif 00726 #define apr_pool_join(a,b) 00727 00728 #ifdef apr_pool_lock 00729 #undef apr_pool_lock 00730 #endif 00731 #define apr_pool_lock(pool, lock) 00732 00733 #endif /* APR_POOL_DEBUG or DOXYGEN */ 00734 00735 /** @} */ 00736 00737 #ifdef __cplusplus 00738 } 00739 #endif 00740 00741 #endif /* !APR_POOLS_H */