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