apr_pools.h revision 251875
1/* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17#ifndef APR_POOLS_H 18#define APR_POOLS_H 19 20/** 21 * @file apr_pools.h 22 * @brief APR memory allocation 23 * 24 * Resource allocation routines... 25 * 26 * designed so that we don't have to keep track of EVERYTHING so that 27 * it can be explicitly freed later (a fundamentally unsound strategy --- 28 * particularly in the presence of die()). 29 * 30 * Instead, we maintain pools, and allocate items (both memory and I/O 31 * handlers) from the pools --- currently there are two, one for 32 * per-transaction info, and one for config info. When a transaction is 33 * over, we can delete everything in the per-transaction apr_pool_t without 34 * fear, and without thinking too hard about it either. 35 * 36 * Note that most operations on pools are not thread-safe: a single pool 37 * should only be accessed by a single thread at any given time. The one 38 * exception to this rule is creating a subpool of a given pool: one or more 39 * threads can safely create subpools at the same time that another thread 40 * accesses the parent pool. 41 */ 42 43#include "apr.h" 44#include "apr_errno.h" 45#include "apr_general.h" /* for APR_STRINGIFY */ 46#define APR_WANT_MEMFUNC /**< for no good reason? */ 47#include "apr_want.h" 48 49#ifdef __cplusplus 50extern "C" { 51#endif 52 53/** 54 * @defgroup apr_pools Memory Pool Functions 55 * @ingroup APR 56 * @{ 57 */ 58 59/** The fundamental pool type */ 60typedef struct apr_pool_t apr_pool_t; 61 62 63/** 64 * Declaration helper macro to construct apr_foo_pool_get()s. 65 * 66 * This standardized macro is used by opaque (APR) data types to return 67 * the apr_pool_t that is associated with the data type. 68 * 69 * APR_POOL_DECLARE_ACCESSOR() is used in a header file to declare the 70 * accessor function. A typical usage and result would be: 71 * <pre> 72 * APR_POOL_DECLARE_ACCESSOR(file); 73 * becomes: 74 * APR_DECLARE(apr_pool_t *) apr_file_pool_get(apr_file_t *ob); 75 * </pre> 76 * @remark Doxygen unwraps this macro (via doxygen.conf) to provide 77 * actual help for each specific occurance of apr_foo_pool_get. 78 * @remark the linkage is specified for APR. It would be possible to expand 79 * the macros to support other linkages. 80 */ 81#define APR_POOL_DECLARE_ACCESSOR(type) \ 82 APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \ 83 (const apr_##type##_t *the##type) 84 85/** 86 * Implementation helper macro to provide apr_foo_pool_get()s. 87 * 88 * In the implementation, the APR_POOL_IMPLEMENT_ACCESSOR() is used to 89 * actually define the function. It assumes the field is named "pool". 90 */ 91#define APR_POOL_IMPLEMENT_ACCESSOR(type) \ 92 APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \ 93 (const apr_##type##_t *the##type) \ 94 { return the##type->pool; } 95 96 97/** 98 * Pool debug levels 99 * 100 * <pre> 101 * | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 102 * --------------------------------- 103 * | | | | | | | | x | General debug code enabled (useful in 104 * combination with --with-efence). 105 * 106 * | | | | | | | x | | Verbose output on stderr (report 107 * CREATE, CLEAR, DESTROY). 108 * 109 * | | | | x | | | | | Verbose output on stderr (report 110 * PALLOC, PCALLOC). 111 * 112 * | | | | | | x | | | Lifetime checking. On each use of a 113 * pool, check its lifetime. If the pool 114 * is out of scope, abort(). 115 * In combination with the verbose flag 116 * above, it will output LIFE in such an 117 * event prior to aborting. 118 * 119 * | | | | | x | | | | Pool owner checking. On each use of a 120 * pool, check if the current thread is the 121 * pools owner. If not, abort(). In 122 * combination with the verbose flag above, 123 * it will output OWNER in such an event 124 * prior to aborting. Use the debug 125 * function apr_pool_owner_set() to switch 126 * a pools ownership. 127 * 128 * When no debug level was specified, assume general debug mode. 129 * If level 0 was specified, debugging is switched off 130 * </pre> 131 */ 132#if defined(APR_POOL_DEBUG) 133/* If APR_POOL_DEBUG is blank, we get 1; if it is a number, we get -1. */ 134#if (APR_POOL_DEBUG - APR_POOL_DEBUG -1 == 1) 135#undef APR_POOL_DEBUG 136#define APR_POOL_DEBUG 1 137#endif 138#else 139#define APR_POOL_DEBUG 0 140#endif 141 142/** the place in the code where the particular function was called */ 143#define APR_POOL__FILE_LINE__ __FILE__ ":" APR_STRINGIFY(__LINE__) 144 145 146 147/** A function that is called when allocation fails. */ 148typedef int (*apr_abortfunc_t)(int retcode); 149 150/* 151 * APR memory structure manipulators (pools, tables, and arrays). 152 */ 153 154/* 155 * Initialization 156 */ 157 158/** 159 * Setup all of the internal structures required to use pools 160 * @remark Programs do NOT need to call this directly. APR will call this 161 * automatically from apr_initialize. 162 * @internal 163 */ 164APR_DECLARE(apr_status_t) apr_pool_initialize(void); 165 166/** 167 * Tear down all of the internal structures required to use pools 168 * @remark Programs do NOT need to call this directly. APR will call this 169 * automatically from apr_terminate. 170 * @internal 171 */ 172APR_DECLARE(void) apr_pool_terminate(void); 173 174 175/* 176 * Pool creation/destruction 177 */ 178 179#include "apr_allocator.h" 180 181/** 182 * Create a new pool. 183 * @param newpool The pool we have just created. 184 * @param parent The parent pool. If this is NULL, the new pool is a root 185 * pool. If it is non-NULL, the new pool will inherit all 186 * of its parent pool's attributes, except the apr_pool_t will 187 * be a sub-pool. 188 * @param abort_fn A function to use if the pool cannot allocate more memory. 189 * @param allocator The allocator to use with the new pool. If NULL the 190 * allocator of the parent pool will be used. 191 * @remark This function is thread-safe, in the sense that multiple threads 192 * can safely create subpools of the same parent pool concurrently. 193 * Similarly, a subpool can be created by one thread at the same 194 * time that another thread accesses the parent pool. 195 */ 196APR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool, 197 apr_pool_t *parent, 198 apr_abortfunc_t abort_fn, 199 apr_allocator_t *allocator); 200 201/** 202 * Create a new pool. 203 * @deprecated @see apr_pool_create_unmanaged_ex. 204 */ 205APR_DECLARE(apr_status_t) apr_pool_create_core_ex(apr_pool_t **newpool, 206 apr_abortfunc_t abort_fn, 207 apr_allocator_t *allocator); 208 209/** 210 * Create a new unmanaged pool. 211 * @param newpool The pool we have just created. 212 * @param abort_fn A function to use if the pool cannot allocate more memory. 213 * @param allocator The allocator to use with the new pool. If NULL a 214 * new allocator will be crated with newpool as owner. 215 * @remark An unmanaged pool is a special pool without a parent; it will 216 * NOT be destroyed upon apr_terminate. It must be explicitly 217 * destroyed by calling apr_pool_destroy, to prevent memory leaks. 218 * Use of this function is discouraged, think twice about whether 219 * you really really need it. 220 */ 221APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex(apr_pool_t **newpool, 222 apr_abortfunc_t abort_fn, 223 apr_allocator_t *allocator); 224 225/** 226 * Debug version of apr_pool_create_ex. 227 * @param newpool @see apr_pool_create. 228 * @param parent @see apr_pool_create. 229 * @param abort_fn @see apr_pool_create. 230 * @param allocator @see apr_pool_create. 231 * @param file_line Where the function is called from. 232 * This is usually APR_POOL__FILE_LINE__. 233 * @remark Only available when APR_POOL_DEBUG is defined. 234 * Call this directly if you have you apr_pool_create_ex 235 * calls in a wrapper function and wish to override 236 * the file_line argument to reflect the caller of 237 * your wrapper function. If you do not have 238 * apr_pool_create_ex in a wrapper, trust the macro 239 * and don't call apr_pool_create_ex_debug directly. 240 */ 241APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool, 242 apr_pool_t *parent, 243 apr_abortfunc_t abort_fn, 244 apr_allocator_t *allocator, 245 const char *file_line); 246 247#if APR_POOL_DEBUG 248#define apr_pool_create_ex(newpool, parent, abort_fn, allocator) \ 249 apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \ 250 APR_POOL__FILE_LINE__) 251#endif 252 253/** 254 * Debug version of apr_pool_create_core_ex. 255 * @deprecated @see apr_pool_create_unmanaged_ex_debug. 256 */ 257APR_DECLARE(apr_status_t) apr_pool_create_core_ex_debug(apr_pool_t **newpool, 258 apr_abortfunc_t abort_fn, 259 apr_allocator_t *allocator, 260 const char *file_line); 261 262/** 263 * Debug version of apr_pool_create_unmanaged_ex. 264 * @param newpool @see apr_pool_create_unmanaged. 265 * @param abort_fn @see apr_pool_create_unmanaged. 266 * @param allocator @see apr_pool_create_unmanaged. 267 * @param file_line Where the function is called from. 268 * This is usually APR_POOL__FILE_LINE__. 269 * @remark Only available when APR_POOL_DEBUG is defined. 270 * Call this directly if you have you apr_pool_create_unmanaged_ex 271 * calls in a wrapper function and wish to override 272 * the file_line argument to reflect the caller of 273 * your wrapper function. If you do not have 274 * apr_pool_create_core_ex in a wrapper, trust the macro 275 * and don't call apr_pool_create_core_ex_debug directly. 276 */ 277APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex_debug(apr_pool_t **newpool, 278 apr_abortfunc_t abort_fn, 279 apr_allocator_t *allocator, 280 const char *file_line); 281 282#if APR_POOL_DEBUG 283#define apr_pool_create_core_ex(newpool, abort_fn, allocator) \ 284 apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \ 285 APR_POOL__FILE_LINE__) 286 287#define apr_pool_create_unmanaged_ex(newpool, abort_fn, allocator) \ 288 apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \ 289 APR_POOL__FILE_LINE__) 290 291#endif 292 293/** 294 * Create a new pool. 295 * @param newpool The pool we have just created. 296 * @param parent The parent pool. If this is NULL, the new pool is a root 297 * pool. If it is non-NULL, the new pool will inherit all 298 * of its parent pool's attributes, except the apr_pool_t will 299 * be a sub-pool. 300 * @remark This function is thread-safe, in the sense that multiple threads 301 * can safely create subpools of the same parent pool concurrently. 302 * Similarly, a subpool can be created by one thread at the same 303 * time that another thread accesses the parent pool. 304 */ 305#if defined(DOXYGEN) 306APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool, 307 apr_pool_t *parent); 308#else 309#if APR_POOL_DEBUG 310#define apr_pool_create(newpool, parent) \ 311 apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \ 312 APR_POOL__FILE_LINE__) 313#else 314#define apr_pool_create(newpool, parent) \ 315 apr_pool_create_ex(newpool, parent, NULL, NULL) 316#endif 317#endif 318 319/** 320 * Create a new pool. 321 * @param newpool The pool we have just created. 322 */ 323#if defined(DOXYGEN) 324APR_DECLARE(apr_status_t) apr_pool_create_core(apr_pool_t **newpool); 325APR_DECLARE(apr_status_t) apr_pool_create_unmanaged(apr_pool_t **newpool); 326#else 327#if APR_POOL_DEBUG 328#define apr_pool_create_core(newpool) \ 329 apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \ 330 APR_POOL__FILE_LINE__) 331#define apr_pool_create_unmanaged(newpool) \ 332 apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \ 333 APR_POOL__FILE_LINE__) 334#else 335#define apr_pool_create_core(newpool) \ 336 apr_pool_create_unmanaged_ex(newpool, NULL, NULL) 337#define apr_pool_create_unmanaged(newpool) \ 338 apr_pool_create_unmanaged_ex(newpool, NULL, NULL) 339#endif 340#endif 341 342/** 343 * Find the pool's allocator 344 * @param pool The pool to get the allocator from. 345 */ 346APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool); 347 348/** 349 * Clear all memory in the pool and run all the cleanups. This also destroys all 350 * subpools. 351 * @param p The pool to clear 352 * @remark This does not actually free the memory, it just allows the pool 353 * to re-use this memory for the next allocation. 354 * @see apr_pool_destroy() 355 */ 356APR_DECLARE(void) apr_pool_clear(apr_pool_t *p); 357 358/** 359 * Debug version of apr_pool_clear. 360 * @param p See: apr_pool_clear. 361 * @param file_line Where the function is called from. 362 * This is usually APR_POOL__FILE_LINE__. 363 * @remark Only available when APR_POOL_DEBUG is defined. 364 * Call this directly if you have you apr_pool_clear 365 * calls in a wrapper function and wish to override 366 * the file_line argument to reflect the caller of 367 * your wrapper function. If you do not have 368 * apr_pool_clear in a wrapper, trust the macro 369 * and don't call apr_pool_destroy_clear directly. 370 */ 371APR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p, 372 const char *file_line); 373 374#if APR_POOL_DEBUG 375#define apr_pool_clear(p) \ 376 apr_pool_clear_debug(p, APR_POOL__FILE_LINE__) 377#endif 378 379/** 380 * Destroy the pool. This takes similar action as apr_pool_clear() and then 381 * frees all the memory. 382 * @param p The pool to destroy 383 * @remark This will actually free the memory 384 */ 385APR_DECLARE(void) apr_pool_destroy(apr_pool_t *p); 386 387/** 388 * Debug version of apr_pool_destroy. 389 * @param p See: apr_pool_destroy. 390 * @param file_line Where the function is called from. 391 * This is usually APR_POOL__FILE_LINE__. 392 * @remark Only available when APR_POOL_DEBUG is defined. 393 * Call this directly if you have you apr_pool_destroy 394 * calls in a wrapper function and wish to override 395 * the file_line argument to reflect the caller of 396 * your wrapper function. If you do not have 397 * apr_pool_destroy in a wrapper, trust the macro 398 * and don't call apr_pool_destroy_debug directly. 399 */ 400APR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p, 401 const char *file_line); 402 403#if APR_POOL_DEBUG 404#define apr_pool_destroy(p) \ 405 apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__) 406#endif 407 408 409/* 410 * Memory allocation 411 */ 412 413/** 414 * Allocate a block of memory from a pool 415 * @param p The pool to allocate from 416 * @param size The amount of memory to allocate 417 * @return The allocated memory 418 */ 419APR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size); 420 421/** 422 * Debug version of apr_palloc 423 * @param p See: apr_palloc 424 * @param size See: apr_palloc 425 * @param file_line Where the function is called from. 426 * This is usually APR_POOL__FILE_LINE__. 427 * @return See: apr_palloc 428 */ 429APR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size, 430 const char *file_line); 431 432#if APR_POOL_DEBUG 433#define apr_palloc(p, size) \ 434 apr_palloc_debug(p, size, APR_POOL__FILE_LINE__) 435#endif 436 437/** 438 * Allocate a block of memory from a pool and set all of the memory to 0 439 * @param p The pool to allocate from 440 * @param size The amount of memory to allocate 441 * @return The allocated memory 442 */ 443#if defined(DOXYGEN) 444APR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size); 445#elif !APR_POOL_DEBUG 446#define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size) 447#endif 448 449/** 450 * Debug version of apr_pcalloc 451 * @param p See: apr_pcalloc 452 * @param size See: apr_pcalloc 453 * @param file_line Where the function is called from. 454 * This is usually APR_POOL__FILE_LINE__. 455 * @return See: apr_pcalloc 456 */ 457APR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size, 458 const char *file_line); 459 460#if APR_POOL_DEBUG 461#define apr_pcalloc(p, size) \ 462 apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__) 463#endif 464 465 466/* 467 * Pool Properties 468 */ 469 470/** 471 * Set the function to be called when an allocation failure occurs. 472 * @remark If the program wants APR to exit on a memory allocation error, 473 * then this function can be called to set the callback to use (for 474 * performing cleanup and then exiting). If this function is not called, 475 * then APR will return an error and expect the calling program to 476 * deal with the error accordingly. 477 */ 478APR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc, 479 apr_pool_t *pool); 480 481/** 482 * Get the abort function associated with the specified pool. 483 * @param pool The pool for retrieving the abort function. 484 * @return The abort function for the given pool. 485 */ 486APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool); 487 488/** 489 * Get the parent pool of the specified pool. 490 * @param pool The pool for retrieving the parent pool. 491 * @return The parent of the given pool. 492 */ 493APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool); 494 495/** 496 * Determine if pool a is an ancestor of pool b. 497 * @param a The pool to search 498 * @param b The pool to search for 499 * @return True if a is an ancestor of b, NULL is considered an ancestor 500 * of all pools. 501 * @remark if compiled with APR_POOL_DEBUG, this function will also 502 * return true if A is a pool which has been guaranteed by the caller 503 * (using apr_pool_join) to have a lifetime at least as long as some 504 * ancestor of pool B. 505 */ 506APR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b); 507 508/** 509 * Tag a pool (give it a name) 510 * @param pool The pool to tag 511 * @param tag The tag 512 */ 513APR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag); 514 515 516/* 517 * User data management 518 */ 519 520/** 521 * Set the data associated with the current pool 522 * @param data The user data associated with the pool. 523 * @param key The key to use for association 524 * @param cleanup The cleanup program to use to cleanup the data (NULL if none) 525 * @param pool The current pool 526 * @warning The data to be attached to the pool should have a life span 527 * at least as long as the pool it is being attached to. 528 * 529 * Users of APR must take EXTREME care when choosing a key to 530 * use for their data. It is possible to accidentally overwrite 531 * data by choosing a key that another part of the program is using. 532 * Therefore it is advised that steps are taken to ensure that unique 533 * keys are used for all of the userdata objects in a particular pool 534 * (the same key in two different pools or a pool and one of its 535 * subpools is okay) at all times. Careful namespace prefixing of 536 * key names is a typical way to help ensure this uniqueness. 537 * 538 */ 539APR_DECLARE(apr_status_t) apr_pool_userdata_set( 540 const void *data, 541 const char *key, 542 apr_status_t (*cleanup)(void *), 543 apr_pool_t *pool); 544 545/** 546 * Set the data associated with the current pool 547 * @param data The user data associated with the pool. 548 * @param key The key to use for association 549 * @param cleanup The cleanup program to use to cleanup the data (NULL if none) 550 * @param pool The current pool 551 * @note same as apr_pool_userdata_set(), except that this version doesn't 552 * make a copy of the key (this function is useful, for example, when 553 * the key is a string literal) 554 * @warning This should NOT be used if the key could change addresses by 555 * any means between the apr_pool_userdata_setn() call and a 556 * subsequent apr_pool_userdata_get() on that key, such as if a 557 * static string is used as a userdata key in a DSO and the DSO could 558 * be unloaded and reloaded between the _setn() and the _get(). You 559 * MUST use apr_pool_userdata_set() in such cases. 560 * @warning More generally, the key and the data to be attached to the 561 * pool should have a life span at least as long as the pool itself. 562 * 563 */ 564APR_DECLARE(apr_status_t) apr_pool_userdata_setn( 565 const void *data, 566 const char *key, 567 apr_status_t (*cleanup)(void *), 568 apr_pool_t *pool); 569 570/** 571 * Return the data associated with the current pool. 572 * @param data The user data associated with the pool. 573 * @param key The key for the data to retrieve 574 * @param pool The current pool. 575 */ 576APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key, 577 apr_pool_t *pool); 578 579 580/** 581 * @defgroup PoolCleanup Pool Cleanup Functions 582 * 583 * Cleanups are performed in the reverse order they were registered. That is: 584 * Last In, First Out. A cleanup function can safely allocate memory from 585 * the pool that is being cleaned up. It can also safely register additional 586 * cleanups which will be run LIFO, directly after the current cleanup 587 * terminates. Cleanups have to take caution in calling functions that 588 * create subpools. Subpools, created during cleanup will NOT automatically 589 * be cleaned up. In other words, cleanups are to clean up after themselves. 590 * 591 * @{ 592 */ 593 594/** 595 * Register a function to be called when a pool is cleared or destroyed 596 * @param p The pool register the cleanup with 597 * @param data The data to pass to the cleanup function. 598 * @param plain_cleanup The function to call when the pool is cleared 599 * or destroyed 600 * @param child_cleanup The function to call when a child process is about 601 * to exec - this function is called in the child, obviously! 602 */ 603APR_DECLARE(void) apr_pool_cleanup_register( 604 apr_pool_t *p, 605 const void *data, 606 apr_status_t (*plain_cleanup)(void *), 607 apr_status_t (*child_cleanup)(void *)); 608 609/** 610 * Register a function to be called when a pool is cleared or destroyed. 611 * 612 * Unlike apr_pool_cleanup_register which register a cleanup 613 * that is called AFTER all subpools are destroyed this function register 614 * a function that will be called before any of the subpool is destoryed. 615 * 616 * @param p The pool register the cleanup with 617 * @param data The data to pass to the cleanup function. 618 * @param plain_cleanup The function to call when the pool is cleared 619 * or destroyed 620 */ 621APR_DECLARE(void) apr_pool_pre_cleanup_register( 622 apr_pool_t *p, 623 const void *data, 624 apr_status_t (*plain_cleanup)(void *)); 625 626/** 627 * Remove a previously registered cleanup function. 628 * 629 * The cleanup most recently registered with @a p having the same values of 630 * @a data and @a cleanup will be removed. 631 * 632 * @param p The pool to remove the cleanup from 633 * @param data The data of the registered cleanup 634 * @param cleanup The function to remove from cleanup 635 * @remarks For some strange reason only the plain_cleanup is handled by this 636 * function 637 */ 638APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data, 639 apr_status_t (*cleanup)(void *)); 640 641/** 642 * Replace the child cleanup function of a previously registered cleanup. 643 * 644 * The cleanup most recently registered with @a p having the same values of 645 * @a data and @a plain_cleanup will have the registered child cleanup 646 * function replaced with @a child_cleanup. 647 * 648 * @param p The pool of the registered cleanup 649 * @param data The data of the registered cleanup 650 * @param plain_cleanup The plain cleanup function of the registered cleanup 651 * @param child_cleanup The function to register as the child cleanup 652 */ 653APR_DECLARE(void) apr_pool_child_cleanup_set( 654 apr_pool_t *p, 655 const void *data, 656 apr_status_t (*plain_cleanup)(void *), 657 apr_status_t (*child_cleanup)(void *)); 658 659/** 660 * Run the specified cleanup function immediately and unregister it. 661 * 662 * The cleanup most recently registered with @a p having the same values of 663 * @a data and @a cleanup will be removed and @a cleanup will be called 664 * with @a data as the argument. 665 * 666 * @param p The pool to remove the cleanup from 667 * @param data The data to remove from cleanup 668 * @param cleanup The function to remove from cleanup 669 */ 670APR_DECLARE(apr_status_t) apr_pool_cleanup_run( 671 apr_pool_t *p, 672 void *data, 673 apr_status_t (*cleanup)(void *)); 674 675/** 676 * An empty cleanup function. 677 * 678 * Passed to apr_pool_cleanup_register() when no cleanup is required. 679 * 680 * @param data The data to cleanup, will not be used by this function. 681 */ 682APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data); 683 684/** 685 * Run all registered child cleanups, in preparation for an exec() 686 * call in a forked child -- close files, etc., but *don't* flush I/O 687 * buffers, *don't* wait for subprocesses, and *don't* free any 688 * memory. 689 */ 690APR_DECLARE(void) apr_pool_cleanup_for_exec(void); 691 692/** @} */ 693 694/** 695 * @defgroup PoolDebug Pool Debugging functions. 696 * 697 * pools have nested lifetimes -- sub_pools are destroyed when the 698 * parent pool is cleared. We allow certain liberties with operations 699 * on things such as tables (and on other structures in a more general 700 * sense) where we allow the caller to insert values into a table which 701 * were not allocated from the table's pool. The table's data will 702 * remain valid as long as all the pools from which its values are 703 * allocated remain valid. 704 * 705 * For example, if B is a sub pool of A, and you build a table T in 706 * pool B, then it's safe to insert data allocated in A or B into T 707 * (because B lives at most as long as A does, and T is destroyed when 708 * B is cleared/destroyed). On the other hand, if S is a table in 709 * pool A, it is safe to insert data allocated in A into S, but it 710 * is *not safe* to insert data allocated from B into S... because 711 * B can be cleared/destroyed before A is (which would leave dangling 712 * pointers in T's data structures). 713 * 714 * In general we say that it is safe to insert data into a table T 715 * if the data is allocated in any ancestor of T's pool. This is the 716 * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor 717 * relationships for all data inserted into tables. APR_POOL_DEBUG also 718 * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other 719 * folks to implement similar restrictions for their own data 720 * structures. 721 * 722 * However, sometimes this ancestor requirement is inconvenient -- 723 * sometimes it's necessary to create a sub pool where the sub pool is 724 * guaranteed to have the same lifetime as the parent pool. This is a 725 * guarantee implemented by the *caller*, not by the pool code. That 726 * is, the caller guarantees they won't destroy the sub pool 727 * individually prior to destroying the parent pool. 728 * 729 * In this case the caller must call apr_pool_join() to indicate this 730 * guarantee to the APR_POOL_DEBUG code. 731 * 732 * These functions are only implemented when #APR_POOL_DEBUG is set. 733 * 734 * @{ 735 */ 736#if APR_POOL_DEBUG || defined(DOXYGEN) 737/** 738 * Guarantee that a subpool has the same lifetime as the parent. 739 * @param p The parent pool 740 * @param sub The subpool 741 */ 742APR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub); 743 744/** 745 * Find a pool from something allocated in it. 746 * @param mem The thing allocated in the pool 747 * @return The pool it is allocated in 748 */ 749APR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem); 750 751/** 752 * Report the number of bytes currently in the pool 753 * @param p The pool to inspect 754 * @param recurse Recurse/include the subpools' sizes 755 * @return The number of bytes 756 */ 757APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse); 758 759/** 760 * Lock a pool 761 * @param pool The pool to lock 762 * @param flag The flag 763 */ 764APR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag); 765 766/* @} */ 767 768#else /* APR_POOL_DEBUG or DOXYGEN */ 769 770#ifdef apr_pool_join 771#undef apr_pool_join 772#endif 773#define apr_pool_join(a,b) 774 775#ifdef apr_pool_lock 776#undef apr_pool_lock 777#endif 778#define apr_pool_lock(pool, lock) 779 780#endif /* APR_POOL_DEBUG or DOXYGEN */ 781 782/** @} */ 783 784#ifdef __cplusplus 785} 786#endif 787 788#endif /* !APR_POOLS_H */ 789