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