home *** CD-ROM | disk | FTP | other *** search
/ Cricao de Sites - 650 Layouts Prontos / WebMasters.iso / Servidores / apache_2.2.8-win32-x86-no_ssl.msi / Data1.cab / _DC97F4089BFD7FF2FE46E283DA1B9162 < prev    next >
Text File  |  2006-08-03  |  25KB  |  671 lines
  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. #endif
  218.  
  219. /**
  220.  * Create a new pool.
  221.  * @param newpool The pool we have just created.
  222.  * @param parent The parent pool.  If this is NULL, the new pool is a root
  223.  *        pool.  If it is non-NULL, the new pool will inherit all
  224.  *        of its parent pool's attributes, except the apr_pool_t will
  225.  *        be a sub-pool.
  226.  */
  227. #if defined(DOXYGEN)
  228. APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool,
  229.                                           apr_pool_t *parent);
  230. #else
  231. #if APR_POOL_DEBUG
  232. #define apr_pool_create(newpool, parent) \
  233.     apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \
  234.                              APR_POOL__FILE_LINE__)
  235. #else
  236. #define apr_pool_create(newpool, parent) \
  237.     apr_pool_create_ex(newpool, parent, NULL, NULL)
  238. #endif
  239. #endif
  240.  
  241. /**
  242.  * Find the pools allocator
  243.  * @param pool The pool to get the allocator from.
  244.  */
  245. APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool);
  246.  
  247. /**
  248.  * Clear all memory in the pool and run all the cleanups. This also destroys all
  249.  * subpools.
  250.  * @param p The pool to clear
  251.  * @remark This does not actually free the memory, it just allows the pool
  252.  *         to re-use this memory for the next allocation.
  253.  * @see apr_pool_destroy()
  254.  */
  255. APR_DECLARE(void) apr_pool_clear(apr_pool_t *p);
  256.  
  257. /**
  258.  * Debug version of apr_pool_clear.
  259.  * @param p See: apr_pool_clear.
  260.  * @param file_line Where the function is called from.
  261.  *        This is usually APR_POOL__FILE_LINE__.
  262.  * @remark Only available when APR_POOL_DEBUG is defined.
  263.  *         Call this directly if you have you apr_pool_clear
  264.  *         calls in a wrapper function and wish to override
  265.  *         the file_line argument to reflect the caller of
  266.  *         your wrapper function.  If you do not have
  267.  *         apr_pool_clear in a wrapper, trust the macro
  268.  *         and don't call apr_pool_destroy_clear directly.
  269.  */
  270. APR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p,
  271.                                        const char *file_line);
  272.  
  273. #if APR_POOL_DEBUG
  274. #define apr_pool_clear(p) \
  275.     apr_pool_clear_debug(p, APR_POOL__FILE_LINE__)
  276. #endif
  277.  
  278. /**
  279.  * Destroy the pool. This takes similar action as apr_pool_clear() and then
  280.  * frees all the memory.
  281.  * @param p The pool to destroy
  282.  * @remark This will actually free the memory
  283.  */
  284. APR_DECLARE(void) apr_pool_destroy(apr_pool_t *p);
  285.  
  286. /**
  287.  * Debug version of apr_pool_destroy.
  288.  * @param p See: apr_pool_destroy.
  289.  * @param file_line Where the function is called from.
  290.  *        This is usually APR_POOL__FILE_LINE__.
  291.  * @remark Only available when APR_POOL_DEBUG is defined.
  292.  *         Call this directly if you have you apr_pool_destroy
  293.  *         calls in a wrapper function and wish to override
  294.  *         the file_line argument to reflect the caller of
  295.  *         your wrapper function.  If you do not have
  296.  *         apr_pool_destroy in a wrapper, trust the macro
  297.  *         and don't call apr_pool_destroy_debug directly.
  298.  */
  299. APR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p,
  300.                                          const char *file_line);
  301.  
  302. #if APR_POOL_DEBUG
  303. #define apr_pool_destroy(p) \
  304.     apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__)
  305. #endif
  306.  
  307.  
  308. /*
  309.  * Memory allocation
  310.  */
  311.  
  312. /**
  313.  * Allocate a block of memory from a pool
  314.  * @param p The pool to allocate from
  315.  * @param size The amount of memory to allocate
  316.  * @return The allocated memory
  317.  */
  318. APR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size);
  319.  
  320. /**
  321.  * Debug version of apr_palloc
  322.  * @param p See: apr_palloc
  323.  * @param size See: apr_palloc
  324.  * @param file_line Where the function is called from.
  325.  *        This is usually APR_POOL__FILE_LINE__.
  326.  * @return See: apr_palloc
  327.  */
  328. APR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size,
  329.                                      const char *file_line);
  330.  
  331. #if APR_POOL_DEBUG
  332. #define apr_palloc(p, size) \
  333.     apr_palloc_debug(p, size, APR_POOL__FILE_LINE__)
  334. #endif
  335.  
  336. /**
  337.  * Allocate a block of memory from a pool and set all of the memory to 0
  338.  * @param p The pool to allocate from
  339.  * @param size The amount of memory to allocate
  340.  * @return The allocated memory
  341.  */
  342. #if defined(DOXYGEN)
  343. APR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size);
  344. #elif !APR_POOL_DEBUG
  345. #define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size)
  346. #endif
  347.  
  348. /**
  349.  * Debug version of apr_pcalloc
  350.  * @param p See: apr_pcalloc
  351.  * @param size See: apr_pcalloc
  352.  * @param file_line Where the function is called from.
  353.  *        This is usually APR_POOL__FILE_LINE__.
  354.  * @return See: apr_pcalloc
  355.  */
  356. APR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size,
  357.                                       const char *file_line);
  358.  
  359. #if APR_POOL_DEBUG
  360. #define apr_pcalloc(p, size) \
  361.     apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__)
  362. #endif
  363.  
  364.  
  365. /*
  366.  * Pool Properties
  367.  */
  368.  
  369. /**
  370.  * Set the function to be called when an allocation failure occurs.
  371.  * @remark If the program wants APR to exit on a memory allocation error,
  372.  *      then this function can be called to set the callback to use (for
  373.  *      performing cleanup and then exiting). If this function is not called,
  374.  *      then APR will return an error and expect the calling program to
  375.  *      deal with the error accordingly.
  376.  */
  377. APR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc,
  378.                                      apr_pool_t *pool);
  379.  
  380. /**
  381.  * Get the abort function associated with the specified pool.
  382.  * @param pool The pool for retrieving the abort function.
  383.  * @return The abort function for the given pool.
  384.  */
  385. APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool);
  386.  
  387. /**
  388.  * Get the parent pool of the specified pool.
  389.  * @param pool The pool for retrieving the parent pool.
  390.  * @return The parent of the given pool.
  391.  */
  392. APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool);
  393.  
  394. /**
  395.  * Determine if pool a is an ancestor of pool b.
  396.  * @param a The pool to search
  397.  * @param b The pool to search for
  398.  * @return True if a is an ancestor of b, NULL is considered an ancestor
  399.  *         of all pools.
  400.  * @remark if compiled with APR_POOL_DEBUG, this function will also
  401.  * return true if A is a pool which has been guaranteed by the caller
  402.  * (using apr_pool_join) to have a lifetime at least as long as some
  403.  * ancestor of pool B.
  404.  */
  405. APR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b);
  406.  
  407. /**
  408.  * Tag a pool (give it a name)
  409.  * @param pool The pool to tag
  410.  * @param tag  The tag
  411.  */
  412. APR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag);
  413.  
  414.  
  415. /*
  416.  * User data management
  417.  */
  418.  
  419. /**
  420.  * Set the data associated with the current pool
  421.  * @param data The user data associated with the pool.
  422.  * @param key The key to use for association
  423.  * @param cleanup The cleanup program to use to cleanup the data (NULL if none)
  424.  * @param pool The current pool
  425.  * @warning The data to be attached to the pool should have a life span
  426.  *          at least as long as the pool it is being attached to.
  427.  *
  428.  *      Users of APR must take EXTREME care when choosing a key to
  429.  *      use for their data.  It is possible to accidentally overwrite
  430.  *      data by choosing a key that another part of the program is using.
  431.  *      Therefore it is advised that steps are taken to ensure that unique
  432.  *      keys are used for all of the userdata objects in a particular pool
  433.  *      (the same key in two different pools or a pool and one of its
  434.  *      subpools is okay) at all times.  Careful namespace prefixing of
  435.  *      key names is a typical way to help ensure this uniqueness.
  436.  *
  437.  */
  438. APR_DECLARE(apr_status_t) apr_pool_userdata_set(
  439.     const void *data,
  440.     const char *key,
  441.     apr_status_t (*cleanup)(void *),
  442.     apr_pool_t *pool);
  443.  
  444. /**
  445.  * Set the data associated with the current pool
  446.  * @param data The user data associated with the pool.
  447.  * @param key The key to use for association
  448.  * @param cleanup The cleanup program to use to cleanup the data (NULL if none)
  449.  * @param pool The current pool
  450.  * @note same as apr_pool_userdata_set(), except that this version doesn't
  451.  *       make a copy of the key (this function is useful, for example, when
  452.  *       the key is a string literal)
  453.  * @warning This should NOT be used if the key could change addresses by
  454.  *       any means between the apr_pool_userdata_setn() call and a
  455.  *       subsequent apr_pool_userdata_get() on that key, such as if a
  456.  *       static string is used as a userdata key in a DSO and the DSO could
  457.  *       be unloaded and reloaded between the _setn() and the _get().  You
  458.  *       MUST use apr_pool_userdata_set() in such cases.
  459.  * @warning More generally, the key and the data to be attached to the
  460.  *       pool should have a life span at least as long as the pool itself.
  461.  *
  462.  */
  463. APR_DECLARE(apr_status_t) apr_pool_userdata_setn(
  464.     const void *data,
  465.     const char *key,
  466.     apr_status_t (*cleanup)(void *),
  467.     apr_pool_t *pool);
  468.  
  469. /**
  470.  * Return the data associated with the current pool.
  471.  * @param data The user data associated with the pool.
  472.  * @param key The key for the data to retrieve
  473.  * @param pool The current pool.
  474.  */
  475. APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key,
  476.                                                 apr_pool_t *pool);
  477.  
  478.  
  479. /**
  480.  * @defgroup PoolCleanup  Pool Cleanup Functions
  481.  *
  482.  * Cleanups are performed in the reverse order they were registered.  That is:
  483.  * Last In, First Out.  A cleanup function can safely allocate memory from
  484.  * the pool that is being cleaned up. It can also safely register additional
  485.  * cleanups which will be run LIFO, directly after the current cleanup
  486.  * terminates.  Cleanups have to take caution in calling functions that
  487.  * create subpools. Subpools, created during cleanup will NOT automatically
  488.  * be cleaned up.  In other words, cleanups are to clean up after themselves.
  489.  *
  490.  * @{
  491.  */
  492.  
  493. /**
  494.  * Register a function to be called when a pool is cleared or destroyed
  495.  * @param p The pool register the cleanup with
  496.  * @param data The data to pass to the cleanup function.
  497.  * @param plain_cleanup The function to call when the pool is cleared
  498.  *                      or destroyed
  499.  * @param child_cleanup The function to call when a child process is about
  500.  *                      to exec - this function is called in the child, obviously!
  501.  */
  502. APR_DECLARE(void) apr_pool_cleanup_register(
  503.     apr_pool_t *p,
  504.     const void *data,
  505.     apr_status_t (*plain_cleanup)(void *),
  506.     apr_status_t (*child_cleanup)(void *));
  507.  
  508. /**
  509.  * Remove a previously registered cleanup function.
  510.  * 
  511.  * The cleanup most recently registered with @a p having the same values of
  512.  * @a data and @a cleanup will be removed.
  513.  *
  514.  * @param p The pool to remove the cleanup from
  515.  * @param data The data of the registered cleanup
  516.  * @param cleanup The function to remove from cleanup
  517.  * @remarks For some strange reason only the plain_cleanup is handled by this
  518.  *          function
  519.  */
  520. APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data,
  521.                                         apr_status_t (*cleanup)(void *));
  522.  
  523. /**
  524.  * Replace the child cleanup function of a previously registered cleanup.
  525.  * 
  526.  * The cleanup most recently registered with @a p having the same values of
  527.  * @a data and @a plain_cleanup will have the registered child cleanup
  528.  * function replaced with @a child_cleanup.
  529.  *
  530.  * @param p The pool of the registered cleanup
  531.  * @param data The data of the registered cleanup
  532.  * @param plain_cleanup The plain cleanup function of the registered cleanup
  533.  * @param child_cleanup The function to register as the child cleanup
  534.  */
  535. APR_DECLARE(void) apr_pool_child_cleanup_set(
  536.     apr_pool_t *p,
  537.     const void *data,
  538.     apr_status_t (*plain_cleanup)(void *),
  539.     apr_status_t (*child_cleanup)(void *));
  540.  
  541. /**
  542.  * Run the specified cleanup function immediately and unregister it.
  543.  *
  544.  * The cleanup most recently registered with @a p having the same values of
  545.  * @a data and @a cleanup will be removed and @a cleanup will be called
  546.  * with @a data as the argument.
  547.  *
  548.  * @param p The pool to remove the cleanup from
  549.  * @param data The data to remove from cleanup
  550.  * @param cleanup The function to remove from cleanup
  551.  */
  552. APR_DECLARE(apr_status_t) apr_pool_cleanup_run(
  553.     apr_pool_t *p,
  554.     void *data,
  555.     apr_status_t (*cleanup)(void *));
  556.  
  557. /**
  558.  * An empty cleanup function.
  559.  * 
  560.  * Passed to apr_pool_cleanup_register() when no cleanup is required.
  561.  *
  562.  * @param data The data to cleanup, will not be used by this function.
  563.  */
  564. APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data);
  565.  
  566. /**
  567.  * Run all registered child cleanups, in preparation for an exec()
  568.  * call in a forked child -- close files, etc., but *don't* flush I/O
  569.  * buffers, *don't* wait for subprocesses, and *don't* free any
  570.  * memory.
  571.  */
  572. APR_DECLARE(void) apr_pool_cleanup_for_exec(void);
  573.  
  574. /** @} */
  575.  
  576. /**
  577.  * @defgroup PoolDebug Pool Debugging functions.
  578.  *
  579.  * pools have nested lifetimes -- sub_pools are destroyed when the
  580.  * parent pool is cleared.  We allow certain liberties with operations
  581.  * on things such as tables (and on other structures in a more general
  582.  * sense) where we allow the caller to insert values into a table which
  583.  * were not allocated from the table's pool.  The table's data will
  584.  * remain valid as long as all the pools from which its values are
  585.  * allocated remain valid.
  586.  *
  587.  * For example, if B is a sub pool of A, and you build a table T in
  588.  * pool B, then it's safe to insert data allocated in A or B into T
  589.  * (because B lives at most as long as A does, and T is destroyed when
  590.  * B is cleared/destroyed).  On the other hand, if S is a table in
  591.  * pool A, it is safe to insert data allocated in A into S, but it
  592.  * is *not safe* to insert data allocated from B into S... because
  593.  * B can be cleared/destroyed before A is (which would leave dangling
  594.  * pointers in T's data structures).
  595.  *
  596.  * In general we say that it is safe to insert data into a table T
  597.  * if the data is allocated in any ancestor of T's pool.  This is the
  598.  * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor
  599.  * relationships for all data inserted into tables.  APR_POOL_DEBUG also
  600.  * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other
  601.  * folks to implement similar restrictions for their own data
  602.  * structures.
  603.  *
  604.  * However, sometimes this ancestor requirement is inconvenient --
  605.  * sometimes it's necessary to create a sub pool where the sub pool is
  606.  * guaranteed to have the same lifetime as the parent pool.  This is a
  607.  * guarantee implemented by the *caller*, not by the pool code.  That
  608.  * is, the caller guarantees they won't destroy the sub pool
  609.  * individually prior to destroying the parent pool.
  610.  *
  611.  * In this case the caller must call apr_pool_join() to indicate this
  612.  * guarantee to the APR_POOL_DEBUG code.
  613.  *
  614.  * These functions are only implemented when #APR_POOL_DEBUG is set.
  615.  *
  616.  * @{
  617.  */
  618. #if APR_POOL_DEBUG || defined(DOXYGEN)
  619. /**
  620.  * Guarantee that a subpool has the same lifetime as the parent.
  621.  * @param p The parent pool
  622.  * @param sub The subpool
  623.  */
  624. APR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub);
  625.  
  626. /**
  627.  * Find a pool from something allocated in it.
  628.  * @param mem The thing allocated in the pool
  629.  * @return The pool it is allocated in
  630.  */
  631. APR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem);
  632.  
  633. /**
  634.  * Report the number of bytes currently in the pool
  635.  * @param p The pool to inspect
  636.  * @param recurse Recurse/include the subpools' sizes
  637.  * @return The number of bytes
  638.  */
  639. APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse);
  640.  
  641. /**
  642.  * Lock a pool
  643.  * @param pool The pool to lock
  644.  * @param flag  The flag
  645.  */
  646. APR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag);
  647.  
  648. /* @} */
  649.  
  650. #else /* APR_POOL_DEBUG or DOXYGEN */
  651.  
  652. #ifdef apr_pool_join
  653. #undef apr_pool_join
  654. #endif
  655. #define apr_pool_join(a,b)
  656.  
  657. #ifdef apr_pool_lock
  658. #undef apr_pool_lock
  659. #endif
  660. #define apr_pool_lock(pool, lock)
  661.  
  662. #endif /* APR_POOL_DEBUG or DOXYGEN */
  663.  
  664. /** @} */
  665.  
  666. #ifdef __cplusplus
  667. }
  668. #endif
  669.  
  670. #endif /* !APR_POOLS_H */
  671.