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