apr_pools.h revision 253734
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 __attribute__((nonnull(1))); 201 202/** 203 * Create a new pool. 204 * @deprecated @see apr_pool_create_unmanaged_ex. 205 */ 206APR_DECLARE(apr_status_t) apr_pool_create_core_ex(apr_pool_t **newpool, 207 apr_abortfunc_t abort_fn, 208 apr_allocator_t *allocator); 209 210/** 211 * Create a new unmanaged pool. 212 * @param newpool The pool we have just created. 213 * @param abort_fn A function to use if the pool cannot allocate more memory. 214 * @param allocator The allocator to use with the new pool. If NULL a 215 * new allocator will be crated with newpool as owner. 216 * @remark An unmanaged pool is a special pool without a parent; it will 217 * NOT be destroyed upon apr_terminate. It must be explicitly 218 * destroyed by calling apr_pool_destroy, to prevent memory leaks. 219 * Use of this function is discouraged, think twice about whether 220 * you really really need it. 221 */ 222APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex(apr_pool_t **newpool, 223 apr_abortfunc_t abort_fn, 224 apr_allocator_t *allocator) 225 __attribute__((nonnull(1))); 226 227/** 228 * Debug version of apr_pool_create_ex. 229 * @param newpool @see apr_pool_create. 230 * @param parent @see apr_pool_create. 231 * @param abort_fn @see apr_pool_create. 232 * @param allocator @see apr_pool_create. 233 * @param file_line Where the function is called from. 234 * This is usually APR_POOL__FILE_LINE__. 235 * @remark Only available when APR_POOL_DEBUG is defined. 236 * Call this directly if you have you apr_pool_create_ex 237 * calls in a wrapper function and wish to override 238 * the file_line argument to reflect the caller of 239 * your wrapper function. If you do not have 240 * apr_pool_create_ex in a wrapper, trust the macro 241 * and don't call apr_pool_create_ex_debug directly. 242 */ 243APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool, 244 apr_pool_t *parent, 245 apr_abortfunc_t abort_fn, 246 apr_allocator_t *allocator, 247 const char *file_line) 248 __attribute__((nonnull(1))); 249 250#if APR_POOL_DEBUG 251#define apr_pool_create_ex(newpool, parent, abort_fn, allocator) \ 252 apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \ 253 APR_POOL__FILE_LINE__) 254#endif 255 256/** 257 * Debug version of apr_pool_create_core_ex. 258 * @deprecated @see apr_pool_create_unmanaged_ex_debug. 259 */ 260APR_DECLARE(apr_status_t) apr_pool_create_core_ex_debug(apr_pool_t **newpool, 261 apr_abortfunc_t abort_fn, 262 apr_allocator_t *allocator, 263 const char *file_line); 264 265/** 266 * Debug version of apr_pool_create_unmanaged_ex. 267 * @param newpool @see apr_pool_create_unmanaged. 268 * @param abort_fn @see apr_pool_create_unmanaged. 269 * @param allocator @see apr_pool_create_unmanaged. 270 * @param file_line Where the function is called from. 271 * This is usually APR_POOL__FILE_LINE__. 272 * @remark Only available when APR_POOL_DEBUG is defined. 273 * Call this directly if you have you apr_pool_create_unmanaged_ex 274 * calls in a wrapper function and wish to override 275 * the file_line argument to reflect the caller of 276 * your wrapper function. If you do not have 277 * apr_pool_create_core_ex in a wrapper, trust the macro 278 * and don't call apr_pool_create_core_ex_debug directly. 279 */ 280APR_DECLARE(apr_status_t) apr_pool_create_unmanaged_ex_debug(apr_pool_t **newpool, 281 apr_abortfunc_t abort_fn, 282 apr_allocator_t *allocator, 283 const char *file_line) 284 __attribute__((nonnull(1))); 285 286#if APR_POOL_DEBUG 287#define apr_pool_create_core_ex(newpool, abort_fn, allocator) \ 288 apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \ 289 APR_POOL__FILE_LINE__) 290 291#define apr_pool_create_unmanaged_ex(newpool, abort_fn, allocator) \ 292 apr_pool_create_unmanaged_ex_debug(newpool, abort_fn, allocator, \ 293 APR_POOL__FILE_LINE__) 294 295#endif 296 297/** 298 * Create a new pool. 299 * @param newpool The pool we have just created. 300 * @param parent The parent pool. If this is NULL, the new pool is a root 301 * pool. If it is non-NULL, the new pool will inherit all 302 * of its parent pool's attributes, except the apr_pool_t will 303 * be a sub-pool. 304 * @remark This function is thread-safe, in the sense that multiple threads 305 * can safely create subpools of the same parent pool concurrently. 306 * Similarly, a subpool can be created by one thread at the same 307 * time that another thread accesses the parent pool. 308 */ 309#if defined(DOXYGEN) 310APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool, 311 apr_pool_t *parent); 312#else 313#if APR_POOL_DEBUG 314#define apr_pool_create(newpool, parent) \ 315 apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \ 316 APR_POOL__FILE_LINE__) 317#else 318#define apr_pool_create(newpool, parent) \ 319 apr_pool_create_ex(newpool, parent, NULL, NULL) 320#endif 321#endif 322 323/** 324 * Create a new pool. 325 * @param newpool The pool we have just created. 326 */ 327#if defined(DOXYGEN) 328APR_DECLARE(apr_status_t) apr_pool_create_core(apr_pool_t **newpool); 329APR_DECLARE(apr_status_t) apr_pool_create_unmanaged(apr_pool_t **newpool); 330#else 331#if APR_POOL_DEBUG 332#define apr_pool_create_core(newpool) \ 333 apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \ 334 APR_POOL__FILE_LINE__) 335#define apr_pool_create_unmanaged(newpool) \ 336 apr_pool_create_unmanaged_ex_debug(newpool, NULL, NULL, \ 337 APR_POOL__FILE_LINE__) 338#else 339#define apr_pool_create_core(newpool) \ 340 apr_pool_create_unmanaged_ex(newpool, NULL, NULL) 341#define apr_pool_create_unmanaged(newpool) \ 342 apr_pool_create_unmanaged_ex(newpool, NULL, NULL) 343#endif 344#endif 345 346/** 347 * Find the pool's allocator 348 * @param pool The pool to get the allocator from. 349 */ 350APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool) 351 __attribute__((nonnull(1))); 352 353/** 354 * Clear all memory in the pool and run all the cleanups. This also destroys all 355 * subpools. 356 * @param p The pool to clear 357 * @remark This does not actually free the memory, it just allows the pool 358 * to re-use this memory for the next allocation. 359 * @see apr_pool_destroy() 360 */ 361APR_DECLARE(void) apr_pool_clear(apr_pool_t *p) __attribute__((nonnull(1))); 362 363/** 364 * Debug version of apr_pool_clear. 365 * @param p See: apr_pool_clear. 366 * @param file_line Where the function is called from. 367 * This is usually APR_POOL__FILE_LINE__. 368 * @remark Only available when APR_POOL_DEBUG is defined. 369 * Call this directly if you have you apr_pool_clear 370 * calls in a wrapper function and wish to override 371 * the file_line argument to reflect the caller of 372 * your wrapper function. If you do not have 373 * apr_pool_clear in a wrapper, trust the macro 374 * and don't call apr_pool_destroy_clear directly. 375 */ 376APR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p, 377 const char *file_line) 378 __attribute__((nonnull(1))); 379 380#if APR_POOL_DEBUG 381#define apr_pool_clear(p) \ 382 apr_pool_clear_debug(p, APR_POOL__FILE_LINE__) 383#endif 384 385/** 386 * Destroy the pool. This takes similar action as apr_pool_clear() and then 387 * frees all the memory. 388 * @param p The pool to destroy 389 * @remark This will actually free the memory 390 */ 391APR_DECLARE(void) apr_pool_destroy(apr_pool_t *p) __attribute__((nonnull(1))); 392 393/** 394 * Debug version of apr_pool_destroy. 395 * @param p See: apr_pool_destroy. 396 * @param file_line Where the function is called from. 397 * This is usually APR_POOL__FILE_LINE__. 398 * @remark Only available when APR_POOL_DEBUG is defined. 399 * Call this directly if you have you apr_pool_destroy 400 * calls in a wrapper function and wish to override 401 * the file_line argument to reflect the caller of 402 * your wrapper function. If you do not have 403 * apr_pool_destroy in a wrapper, trust the macro 404 * and don't call apr_pool_destroy_debug directly. 405 */ 406APR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p, 407 const char *file_line) 408 __attribute__((nonnull(1))); 409 410#if APR_POOL_DEBUG 411#define apr_pool_destroy(p) \ 412 apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__) 413#endif 414 415 416/* 417 * Memory allocation 418 */ 419 420/** 421 * Allocate a block of memory from a pool 422 * @param p The pool to allocate from 423 * @param size The amount of memory to allocate 424 * @return The allocated memory 425 */ 426APR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size) 427#if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4)) 428 __attribute__((alloc_size(2))) 429#endif 430 __attribute__((nonnull(1))); 431 432/** 433 * Debug version of apr_palloc 434 * @param p See: apr_palloc 435 * @param size See: apr_palloc 436 * @param file_line Where the function is called from. 437 * This is usually APR_POOL__FILE_LINE__. 438 * @return See: apr_palloc 439 */ 440APR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size, 441 const char *file_line) 442#if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4)) 443 __attribute__((alloc_size(2))) 444#endif 445 __attribute__((nonnull(1))); 446 447#if APR_POOL_DEBUG 448#define apr_palloc(p, size) \ 449 apr_palloc_debug(p, size, APR_POOL__FILE_LINE__) 450#endif 451 452/** 453 * Allocate a block of memory from a pool and set all of the memory to 0 454 * @param p The pool to allocate from 455 * @param size The amount of memory to allocate 456 * @return The allocated memory 457 */ 458#if defined(DOXYGEN) 459APR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size); 460#elif !APR_POOL_DEBUG 461#define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size) 462#endif 463 464/** 465 * Debug version of apr_pcalloc 466 * @param p See: apr_pcalloc 467 * @param size See: apr_pcalloc 468 * @param file_line Where the function is called from. 469 * This is usually APR_POOL__FILE_LINE__. 470 * @return See: apr_pcalloc 471 */ 472APR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size, 473 const char *file_line) 474 __attribute__((nonnull(1))); 475 476#if APR_POOL_DEBUG 477#define apr_pcalloc(p, size) \ 478 apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__) 479#endif 480 481 482/* 483 * Pool Properties 484 */ 485 486/** 487 * Set the function to be called when an allocation failure occurs. 488 * @remark If the program wants APR to exit on a memory allocation error, 489 * then this function can be called to set the callback to use (for 490 * performing cleanup and then exiting). If this function is not called, 491 * then APR will return an error and expect the calling program to 492 * deal with the error accordingly. 493 */ 494APR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc, 495 apr_pool_t *pool) 496 __attribute__((nonnull(2))); 497 498/** 499 * Get the abort function associated with the specified pool. 500 * @param pool The pool for retrieving the abort function. 501 * @return The abort function for the given pool. 502 */ 503APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool) 504 __attribute__((nonnull(1))); 505 506/** 507 * Get the parent pool of the specified pool. 508 * @param pool The pool for retrieving the parent pool. 509 * @return The parent of the given pool. 510 */ 511APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool) 512 __attribute__((nonnull(1))); 513 514/** 515 * Determine if pool a is an ancestor of pool b. 516 * @param a The pool to search 517 * @param b The pool to search for 518 * @return True if a is an ancestor of b, NULL is considered an ancestor 519 * of all pools. 520 * @remark if compiled with APR_POOL_DEBUG, this function will also 521 * return true if A is a pool which has been guaranteed by the caller 522 * (using apr_pool_join) to have a lifetime at least as long as some 523 * ancestor of pool B. 524 */ 525APR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b); 526 527/** 528 * Tag a pool (give it a name) 529 * @param pool The pool to tag 530 * @param tag The tag 531 */ 532APR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag) 533 __attribute__((nonnull(1))); 534 535 536/* 537 * User data management 538 */ 539 540/** 541 * Set the data associated with the current pool 542 * @param data The user data associated with the pool. 543 * @param key The key to use for association 544 * @param cleanup The cleanup program to use to cleanup the data (NULL if none) 545 * @param pool The current pool 546 * @warning The data to be attached to the pool should have a life span 547 * at least as long as the pool it is being attached to. 548 * 549 * Users of APR must take EXTREME care when choosing a key to 550 * use for their data. It is possible to accidentally overwrite 551 * data by choosing a key that another part of the program is using. 552 * Therefore it is advised that steps are taken to ensure that unique 553 * keys are used for all of the userdata objects in a particular pool 554 * (the same key in two different pools or a pool and one of its 555 * subpools is okay) at all times. Careful namespace prefixing of 556 * key names is a typical way to help ensure this uniqueness. 557 * 558 */ 559APR_DECLARE(apr_status_t) apr_pool_userdata_set(const void *data, 560 const char *key, 561 apr_status_t (*cleanup)(void *), 562 apr_pool_t *pool) 563 __attribute__((nonnull(2,4))); 564 565/** 566 * Set the data associated with the current pool 567 * @param data The user data associated with the pool. 568 * @param key The key to use for association 569 * @param cleanup The cleanup program to use to cleanup the data (NULL if none) 570 * @param pool The current pool 571 * @note same as apr_pool_userdata_set(), except that this version doesn't 572 * make a copy of the key (this function is useful, for example, when 573 * the key is a string literal) 574 * @warning This should NOT be used if the key could change addresses by 575 * any means between the apr_pool_userdata_setn() call and a 576 * subsequent apr_pool_userdata_get() on that key, such as if a 577 * static string is used as a userdata key in a DSO and the DSO could 578 * be unloaded and reloaded between the _setn() and the _get(). You 579 * MUST use apr_pool_userdata_set() in such cases. 580 * @warning More generally, the key and the data to be attached to the 581 * pool should have a life span at least as long as the pool itself. 582 * 583 */ 584APR_DECLARE(apr_status_t) apr_pool_userdata_setn( 585 const void *data, const char *key, 586 apr_status_t (*cleanup)(void *), 587 apr_pool_t *pool) 588 __attribute__((nonnull(2,4))); 589 590/** 591 * Return the data associated with the current pool. 592 * @param data The user data associated with the pool. 593 * @param key The key for the data to retrieve 594 * @param pool The current pool. 595 */ 596APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key, 597 apr_pool_t *pool) 598 __attribute__((nonnull(1,2,3))); 599 600 601/** 602 * @defgroup PoolCleanup Pool Cleanup Functions 603 * 604 * Cleanups are performed in the reverse order they were registered. That is: 605 * Last In, First Out. A cleanup function can safely allocate memory from 606 * the pool that is being cleaned up. It can also safely register additional 607 * cleanups which will be run LIFO, directly after the current cleanup 608 * terminates. Cleanups have to take caution in calling functions that 609 * create subpools. Subpools, created during cleanup will NOT automatically 610 * be cleaned up. In other words, cleanups are to clean up after themselves. 611 * 612 * @{ 613 */ 614 615/** 616 * Register a function to be called when a pool is cleared or destroyed 617 * @param p The pool register the cleanup with 618 * @param data The data to pass to the cleanup function. 619 * @param plain_cleanup The function to call when the pool is cleared 620 * or destroyed 621 * @param child_cleanup The function to call when a child process is about 622 * to exec - this function is called in the child, obviously! 623 */ 624APR_DECLARE(void) apr_pool_cleanup_register( 625 apr_pool_t *p, const void *data, 626 apr_status_t (*plain_cleanup)(void *), 627 apr_status_t (*child_cleanup)(void *)) 628 __attribute__((nonnull(3,4))); 629 630/** 631 * Register a function to be called when a pool is cleared or destroyed. 632 * 633 * Unlike apr_pool_cleanup_register which register a cleanup 634 * that is called AFTER all subpools are destroyed this function register 635 * a function that will be called before any of the subpool is destoryed. 636 * 637 * @param p The pool register the cleanup with 638 * @param data The data to pass to the cleanup function. 639 * @param plain_cleanup The function to call when the pool is cleared 640 * or destroyed 641 */ 642APR_DECLARE(void) apr_pool_pre_cleanup_register( 643 apr_pool_t *p, const void *data, 644 apr_status_t (*plain_cleanup)(void *)) 645 __attribute__((nonnull(3))); 646 647/** 648 * Remove a previously registered cleanup function. 649 * 650 * The cleanup most recently registered with @a p having the same values of 651 * @a data and @a cleanup will be removed. 652 * 653 * @param p The pool to remove the cleanup from 654 * @param data The data of the registered cleanup 655 * @param cleanup The function to remove from cleanup 656 * @remarks For some strange reason only the plain_cleanup is handled by this 657 * function 658 */ 659APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data, 660 apr_status_t (*cleanup)(void *)) 661 __attribute__((nonnull(3))); 662 663/** 664 * Replace the child cleanup function of a previously registered cleanup. 665 * 666 * The cleanup most recently registered with @a p having the same values of 667 * @a data and @a plain_cleanup will have the registered child cleanup 668 * function replaced with @a child_cleanup. 669 * 670 * @param p The pool of the registered cleanup 671 * @param data The data of the registered cleanup 672 * @param plain_cleanup The plain cleanup function of the registered cleanup 673 * @param child_cleanup The function to register as the child cleanup 674 */ 675APR_DECLARE(void) apr_pool_child_cleanup_set( 676 apr_pool_t *p, const void *data, 677 apr_status_t (*plain_cleanup)(void *), 678 apr_status_t (*child_cleanup)(void *)) 679 __attribute__((nonnull(3,4))); 680 681/** 682 * Run the specified cleanup function immediately and unregister it. 683 * 684 * The cleanup most recently registered with @a p having the same values of 685 * @a data and @a cleanup will be removed and @a cleanup will be called 686 * with @a data as the argument. 687 * 688 * @param p The pool to remove the cleanup from 689 * @param data The data to remove from cleanup 690 * @param cleanup The function to remove from cleanup 691 */ 692APR_DECLARE(apr_status_t) apr_pool_cleanup_run(apr_pool_t *p, void *data, 693 apr_status_t (*cleanup)(void *)) 694 __attribute__((nonnull(3))); 695 696/** 697 * An empty cleanup function. 698 * 699 * Passed to apr_pool_cleanup_register() when no cleanup is required. 700 * 701 * @param data The data to cleanup, will not be used by this function. 702 */ 703APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data); 704 705/** 706 * Run all registered child cleanups, in preparation for an exec() 707 * call in a forked child -- close files, etc., but *don't* flush I/O 708 * buffers, *don't* wait for subprocesses, and *don't* free any 709 * memory. 710 */ 711APR_DECLARE(void) apr_pool_cleanup_for_exec(void); 712 713/** @} */ 714 715/** 716 * @defgroup PoolDebug Pool Debugging functions. 717 * 718 * pools have nested lifetimes -- sub_pools are destroyed when the 719 * parent pool is cleared. We allow certain liberties with operations 720 * on things such as tables (and on other structures in a more general 721 * sense) where we allow the caller to insert values into a table which 722 * were not allocated from the table's pool. The table's data will 723 * remain valid as long as all the pools from which its values are 724 * allocated remain valid. 725 * 726 * For example, if B is a sub pool of A, and you build a table T in 727 * pool B, then it's safe to insert data allocated in A or B into T 728 * (because B lives at most as long as A does, and T is destroyed when 729 * B is cleared/destroyed). On the other hand, if S is a table in 730 * pool A, it is safe to insert data allocated in A into S, but it 731 * is *not safe* to insert data allocated from B into S... because 732 * B can be cleared/destroyed before A is (which would leave dangling 733 * pointers in T's data structures). 734 * 735 * In general we say that it is safe to insert data into a table T 736 * if the data is allocated in any ancestor of T's pool. This is the 737 * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor 738 * relationships for all data inserted into tables. APR_POOL_DEBUG also 739 * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other 740 * folks to implement similar restrictions for their own data 741 * structures. 742 * 743 * However, sometimes this ancestor requirement is inconvenient -- 744 * sometimes it's necessary to create a sub pool where the sub pool is 745 * guaranteed to have the same lifetime as the parent pool. This is a 746 * guarantee implemented by the *caller*, not by the pool code. That 747 * is, the caller guarantees they won't destroy the sub pool 748 * individually prior to destroying the parent pool. 749 * 750 * In this case the caller must call apr_pool_join() to indicate this 751 * guarantee to the APR_POOL_DEBUG code. 752 * 753 * These functions are only implemented when #APR_POOL_DEBUG is set. 754 * 755 * @{ 756 */ 757#if APR_POOL_DEBUG || defined(DOXYGEN) 758/** 759 * Guarantee that a subpool has the same lifetime as the parent. 760 * @param p The parent pool 761 * @param sub The subpool 762 */ 763APR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub) 764 __attribute__((nonnull(2))); 765 766/** 767 * Find a pool from something allocated in it. 768 * @param mem The thing allocated in the pool 769 * @return The pool it is allocated in 770 */ 771APR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem); 772 773/** 774 * Report the number of bytes currently in the pool 775 * @param p The pool to inspect 776 * @param recurse Recurse/include the subpools' sizes 777 * @return The number of bytes 778 */ 779APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse) 780 __attribute__((nonnull(1))); 781 782/** 783 * Lock a pool 784 * @param pool The pool to lock 785 * @param flag The flag 786 */ 787APR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag); 788 789/* @} */ 790 791#else /* APR_POOL_DEBUG or DOXYGEN */ 792 793#ifdef apr_pool_join 794#undef apr_pool_join 795#endif 796#define apr_pool_join(a,b) 797 798#ifdef apr_pool_lock 799#undef apr_pool_lock 800#endif 801#define apr_pool_lock(pool, lock) 802 803#endif /* APR_POOL_DEBUG or DOXYGEN */ 804 805/** @} */ 806 807#ifdef __cplusplus 808} 809#endif 810 811#endif /* !APR_POOLS_H */ 812