Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

apr_pools.h

Go to the documentation of this file.
00001 /* Copyright 2000-2004 The Apache Software Foundation
00002  *
00003  * Licensed under the Apache License, Version 2.0 (the "License");
00004  * you may not use this file except in compliance with the License.
00005  * You may obtain a copy of the License at
00006  *
00007  *     http://www.apache.org/licenses/LICENSE-2.0
00008  *
00009  * Unless required by applicable law or agreed to in writing, software
00010  * distributed under the License is distributed on an "AS IS" BASIS,
00011  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00012  * See the License for the specific language governing permissions and
00013  * limitations under the License.
00014  */
00015 
00016 #ifndef APR_POOLS_H
00017 #define APR_POOLS_H
00018 
00019 /**
00020  * @file apr_pools.h
00021  * @brief APR memory allocation
00022  *
00023  * Resource allocation routines...
00024  *
00025  * designed so that we don't have to keep track of EVERYTHING so that
00026  * it can be explicitly freed later (a fundamentally unsound strategy ---
00027  * particularly in the presence of die()).
00028  *
00029  * Instead, we maintain pools, and allocate items (both memory and I/O
00030  * handlers) from the pools --- currently there are two, one for per
00031  * transaction info, and one for config info.  When a transaction is over,
00032  * we can delete everything in the per-transaction apr_pool_t without fear,
00033  * and without thinking too hard about it either.
00034  */
00035 
00036 #include "apr.h"
00037 #include "apr_errno.h"
00038 #include "apr_general.h" /* for APR_STRINGIFY */
00039 #define APR_WANT_MEMFUNC /**< for no good reason? */
00040 #include "apr_want.h"
00041 
00042 #ifdef __cplusplus
00043 extern "C" {
00044 #endif
00045 
00046 /**
00047  * @defgroup apr_pools Memory Pool Functions
00048  * @ingroup APR 
00049  * @{
00050  */
00051 
00052 /** The fundamental pool type */
00053 typedef struct apr_pool_t apr_pool_t;
00054 
00055 
00056 /**
00057  * Declaration helper macro to construct apr_foo_pool_get()s.
00058  *
00059  * This standardized macro is used by opaque (APR) data types to return
00060  * the apr_pool_t that is associated with the data type.
00061  *
00062  * APR_POOL_DECLARE_ACCESSOR() is used in a header file to declare the
00063  * accessor function. A typical usage and result would be:
00064  * <pre>
00065  *    APR_POOL_DECLARE_ACCESSOR(file);
00066  * becomes:
00067  *    APR_DECLARE(apr_pool_t *) apr_file_pool_get(apr_file_t *ob);
00068  * </pre>
00069  * @remark Doxygen unwraps this macro (via doxygen.conf) to provide 
00070  * actual help for each specific occurance of apr_foo_pool_get.
00071  * @remark the linkage is specified for APR. It would be possible to expand
00072  *       the macros to support other linkages.
00073  */
00074 #define APR_POOL_DECLARE_ACCESSOR(type) \
00075     APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \
00076         (const apr_##type##_t *the##type)
00077 
00078 /** 
00079  * Implementation helper macro to provide apr_foo_pool_get()s.
00080  *
00081  * In the implementation, the APR_POOL_IMPLEMENT_ACCESSOR() is used to
00082  * actually define the function. It assumes the field is named "pool".
00083  */
00084 #define APR_POOL_IMPLEMENT_ACCESSOR(type) \
00085     APR_DECLARE(apr_pool_t *) apr_##type##_pool_get \
00086             (const apr_##type##_t *the##type) \
00087         { return the##type->pool; }
00088 
00089 
00090 /**
00091  * Pool debug levels
00092  *
00093  * <pre>
00094  * | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
00095  * ---------------------------------
00096  * |   |   |   |   |   |   |   | x |  General debug code enabled (useful in
00097  *                                    combination with --with-efence).
00098  *
00099  * |   |   |   |   |   |   | x |   |  Verbose output on stderr (report
00100  *                                    CREATE, CLEAR, DESTROY).
00101  *
00102  * |   |   |   | x |   |   |   |   |  Verbose output on stderr (report
00103  *                                    PALLOC, PCALLOC).
00104  *
00105  * |   |   |   |   |   | x |   |   |  Lifetime checking. On each use of a
00106  *                                    pool, check its lifetime.  If the pool
00107  *                                    is out of scope, abort().
00108  *                                    In combination with the verbose flag
00109  *                                    above, it will output LIFE in such an
00110  *                                    event prior to aborting.
00111  *
00112  * |   |   |   |   | x |   |   |   |  Pool owner checking.  On each use of a
00113  *                                    pool, check if the current thread is the
00114  *                                    pools owner.  If not, abort().  In
00115  *                                    combination with the verbose flag above,
00116  *                                    it will output OWNER in such an event
00117  *                                    prior to aborting.  Use the debug
00118  *                                    function apr_pool_owner_set() to switch
00119  *                                    a pools ownership.
00120  *
00121  * When no debug level was specified, assume general debug mode.
00122  * If level 0 was specified, debugging is switched off
00123  * </pre>
00124  */
00125 #if defined(APR_POOL_DEBUG)
00126 /* If APR_POOL_DEBUG is blank, we get 1; if it is a number, we get -1. */
00127 #if (APR_POOL_DEBUG - APR_POOL_DEBUG -1 == 1)
00128 #undef APR_POOL_DEBUG
00129 #define APR_POOL_DEBUG 1
00130 #endif
00131 #else
00132 #define APR_POOL_DEBUG 0
00133 #endif
00134 
00135 /** the place in the code where the particular function was called */
00136 #define APR_POOL__FILE_LINE__ __FILE__ ":" APR_STRINGIFY(__LINE__)
00137 
00138 
00139 
00140 /** A function that is called when allocation fails. */
00141 typedef int (*apr_abortfunc_t)(int retcode);
00142 
00143 /*
00144  * APR memory structure manipulators (pools, tables, and arrays).
00145  */
00146 
00147 /*
00148  * Initialization
00149  */
00150 
00151 /**
00152  * Setup all of the internal structures required to use pools
00153  * @remark Programs do NOT need to call this directly.  APR will call this
00154  *      automatically from apr_initialize.
00155  * @internal
00156  */
00157 APR_DECLARE(apr_status_t) apr_pool_initialize(void);
00158 
00159 /**
00160  * Tear down all of the internal structures required to use pools
00161  * @remark Programs do NOT need to call this directly.  APR will call this
00162  *      automatically from apr_terminate.
00163  * @internal
00164  */
00165 APR_DECLARE(void) apr_pool_terminate(void);
00166 
00167 
00168 /*
00169  * Pool creation/destruction
00170  */
00171 
00172 #include "apr_allocator.h"
00173 
00174 /**
00175  * Create a new pool.
00176  * @param newpool The pool we have just created.
00177  * @param parent The parent pool.  If this is NULL, the new pool is a root
00178  *        pool.  If it is non-NULL, the new pool will inherit all
00179  *        of its parent pool's attributes, except the apr_pool_t will
00180  *        be a sub-pool.
00181  * @param abort_fn A function to use if the pool cannot allocate more memory.
00182  * @param allocator The allocator to use with the new pool.  If NULL the
00183  *        allocator of the parent pool will be used.
00184  */
00185 APR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool,
00186                                              apr_pool_t *parent,
00187                                              apr_abortfunc_t abort_fn,
00188                                              apr_allocator_t *allocator);
00189 
00190 /**
00191  * Debug version of apr_pool_create_ex.
00192  * @param newpool @see apr_pool_create.
00193  * @param parent @see apr_pool_create.
00194  * @param abort_fn @see apr_pool_create.
00195  * @param allocator @see apr_pool_create.
00196  * @param file_line Where the function is called from.
00197  *        This is usually APR_POOL__FILE_LINE__.
00198  * @remark Only available when APR_POOL_DEBUG is defined.
00199  *         Call this directly if you have you apr_pool_create_ex
00200  *         calls in a wrapper function and wish to override
00201  *         the file_line argument to reflect the caller of
00202  *         your wrapper function.  If you do not have
00203  *         apr_pool_create_ex in a wrapper, trust the macro
00204  *         and don't call apr_pool_create_ex_debug directly.
00205  */
00206 APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool,
00207                                                    apr_pool_t *parent,
00208                                                    apr_abortfunc_t abort_fn,
00209                                                    apr_allocator_t *allocator,
00210                                                    const char *file_line);
00211 
00212 #if APR_POOL_DEBUG
00213 #define apr_pool_create_ex(newpool, parent, abort_fn, allocator)  \
00214     apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \
00215                              APR_POOL__FILE_LINE__)
00216 #endif
00217 
00218 /**
00219  * Create a new pool.
00220  * @param newpool The pool we have just created.
00221  * @param parent The parent pool.  If this is NULL, the new pool is a root
00222  *        pool.  If it is non-NULL, the new pool will inherit all
00223  *        of its parent pool's attributes, except the apr_pool_t will
00224  *        be a sub-pool.
00225  */
00226 #if defined(DOXYGEN)
00227 APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool,
00228                                           apr_pool_t *parent);
00229 #else
00230 #if APR_POOL_DEBUG
00231 #define apr_pool_create(newpool, parent) \
00232     apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \
00233                              APR_POOL__FILE_LINE__)
00234 #else
00235 #define apr_pool_create(newpool, parent) \
00236     apr_pool_create_ex(newpool, parent, NULL, NULL)
00237 #endif
00238 #endif
00239 
00240 /**
00241  * Find the pools allocator
00242  * @param pool The pool to get the allocator from.
00243  */
00244 APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool);
00245 
00246 /**
00247  * Clear all memory in the pool and run all the cleanups. This also destroys all
00248  * subpools.
00249  * @param p The pool to clear
00250  * @remark This does not actually free the memory, it just allows the pool
00251  *         to re-use this memory for the next allocation.
00252  * @see apr_pool_destroy()
00253  */
00254 APR_DECLARE(void) apr_pool_clear(apr_pool_t *p);
00255 
00256 /**
00257  * Debug version of apr_pool_clear.
00258  * @param p See: apr_pool_clear.
00259  * @param file_line Where the function is called from.
00260  *        This is usually APR_POOL__FILE_LINE__.
00261  * @remark Only available when APR_POOL_DEBUG is defined.
00262  *         Call this directly if you have you apr_pool_clear
00263  *         calls in a wrapper function and wish to override
00264  *         the file_line argument to reflect the caller of
00265  *         your wrapper function.  If you do not have
00266  *         apr_pool_clear in a wrapper, trust the macro
00267  *         and don't call apr_pool_destroy_clear directly.
00268  */
00269 APR_DECLARE(void) apr_pool_clear_debug(apr_pool_t *p,
00270                                        const char *file_line);
00271 
00272 #if APR_POOL_DEBUG
00273 #define apr_pool_clear(p) \
00274     apr_pool_clear_debug(p, APR_POOL__FILE_LINE__)
00275 #endif
00276 
00277 /**
00278  * Destroy the pool. This takes similar action as apr_pool_clear() and then
00279  * frees all the memory.
00280  * @param p The pool to destroy
00281  * @remark This will actually free the memory
00282  */
00283 APR_DECLARE(void) apr_pool_destroy(apr_pool_t *p);
00284 
00285 /**
00286  * Debug version of apr_pool_destroy.
00287  * @param p See: apr_pool_destroy.
00288  * @param file_line Where the function is called from.
00289  *        This is usually APR_POOL__FILE_LINE__.
00290  * @remark Only available when APR_POOL_DEBUG is defined.
00291  *         Call this directly if you have you apr_pool_destroy
00292  *         calls in a wrapper function and wish to override
00293  *         the file_line argument to reflect the caller of
00294  *         your wrapper function.  If you do not have
00295  *         apr_pool_destroy in a wrapper, trust the macro
00296  *         and don't call apr_pool_destroy_debug directly.
00297  */
00298 APR_DECLARE(void) apr_pool_destroy_debug(apr_pool_t *p,
00299                                          const char *file_line);
00300 
00301 #if APR_POOL_DEBUG
00302 #define apr_pool_destroy(p) \
00303     apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__)
00304 #endif
00305 
00306 
00307 /*
00308  * Memory allocation
00309  */
00310 
00311 /**
00312  * Allocate a block of memory from a pool
00313  * @param p The pool to allocate from
00314  * @param size The amount of memory to allocate
00315  * @return The allocated memory
00316  */
00317 APR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size);
00318 
00319 /**
00320  * Debug version of apr_palloc
00321  * @param p See: apr_palloc
00322  * @param size See: apr_palloc
00323  * @param file_line Where the function is called from.
00324  *        This is usually APR_POOL__FILE_LINE__.
00325  * @return See: apr_palloc
00326  */
00327 APR_DECLARE(void *) apr_palloc_debug(apr_pool_t *p, apr_size_t size,
00328                                      const char *file_line);
00329 
00330 #if APR_POOL_DEBUG
00331 #define apr_palloc(p, size) \
00332     apr_palloc_debug(p, size, APR_POOL__FILE_LINE__)
00333 #endif
00334 
00335 /**
00336  * Allocate a block of memory from a pool and set all of the memory to 0
00337  * @param p The pool to allocate from
00338  * @param size The amount of memory to allocate
00339  * @return The allocated memory
00340  */
00341 #if defined(DOXYGEN)
00342 APR_DECLARE(void *) apr_pcalloc(apr_pool_t *p, apr_size_t size);
00343 #elif !APR_POOL_DEBUG
00344 #define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size)
00345 #endif
00346 
00347 /**
00348  * Debug version of apr_pcalloc
00349  * @param p See: apr_pcalloc
00350  * @param size See: apr_pcalloc
00351  * @param file_line Where the function is called from.
00352  *        This is usually APR_POOL__FILE_LINE__.
00353  * @return See: apr_pcalloc
00354  */
00355 APR_DECLARE(void *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size,
00356                                       const char *file_line);
00357 
00358 #if APR_POOL_DEBUG
00359 #define apr_pcalloc(p, size) \
00360     apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__)
00361 #endif
00362 
00363 
00364 /*
00365  * Pool Properties
00366  */
00367 
00368 /**
00369  * Set the function to be called when an allocation failure occurs.
00370  * @remark If the program wants APR to exit on a memory allocation error,
00371  *      then this function can be called to set the callback to use (for
00372  *      performing cleanup and then exiting). If this function is not called,
00373  *      then APR will return an error and expect the calling program to
00374  *      deal with the error accordingly.
00375  */
00376 APR_DECLARE(void) apr_pool_abort_set(apr_abortfunc_t abortfunc,
00377                                      apr_pool_t *pool);
00378 
00379 /**
00380  * Get the abort function associated with the specified pool.
00381  * @param pool The pool for retrieving the abort function.
00382  * @return The abort function for the given pool.
00383  */
00384 APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool);
00385 
00386 /**
00387  * Get the parent pool of the specified pool.
00388  * @param pool The pool for retrieving the parent pool.
00389  * @return The parent of the given pool.
00390  */
00391 APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool);
00392 
00393 /**
00394  * Determine if pool a is an ancestor of pool b
00395  * @param a The pool to search
00396  * @param b The pool to search for
00397  * @return True if a is an ancestor of b, NULL is considered an ancestor
00398  *         of all pools.
00399  */
00400 APR_DECLARE(int) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b);
00401 
00402 /**
00403  * Tag a pool (give it a name)
00404  * @param pool The pool to tag
00405  * @param tag  The tag
00406  */
00407 APR_DECLARE(void) apr_pool_tag(apr_pool_t *pool, const char *tag);
00408 
00409 
00410 /*
00411  * User data management
00412  */
00413 
00414 /**
00415  * Set the data associated with the current pool
00416  * @param data The user data associated with the pool.
00417  * @param key The key to use for association
00418  * @param cleanup The cleanup program to use to cleanup the data (NULL if none)
00419  * @param pool The current pool
00420  * @warning The data to be attached to the pool should have a life span
00421  *          at least as long as the pool it is being attached to.
00422  *
00423  *      Users of APR must take EXTREME care when choosing a key to
00424  *      use for their data.  It is possible to accidentally overwrite
00425  *      data by choosing a key that another part of the program is using.
00426  *      Therefore it is advised that steps are taken to ensure that unique
00427  *      keys are used for all of the userdata objects in a particular pool
00428  *      (the same key in two different pools or a pool and one of its
00429  *      subpools is okay) at all times.  Careful namespace prefixing of
00430  *      key names is a typical way to help ensure this uniqueness.
00431  *
00432  */
00433 APR_DECLARE(apr_status_t) apr_pool_userdata_set(
00434     const void *data,
00435     const char *key,
00436     apr_status_t (*cleanup)(void *),
00437     apr_pool_t *pool);
00438 
00439 /**
00440  * Set the data associated with the current pool
00441  * @param data The user data associated with the pool.
00442  * @param key The key to use for association
00443  * @param cleanup The cleanup program to use to cleanup the data (NULL if none)
00444  * @param pool The current pool
00445  * @note same as apr_pool_userdata_set(), except that this version doesn't
00446  *       make a copy of the key (this function is useful, for example, when
00447  *       the key is a string literal)
00448  * @warning This should NOT be used if the key could change addresses by
00449  *       any means between the apr_pool_userdata_setn() call and a
00450  *       subsequent apr_pool_userdata_get() on that key, such as if a
00451  *       static string is used as a userdata key in a DSO and the DSO could
00452  *       be unloaded and reloaded between the _setn() and the _get().  You
00453  *       MUST use apr_pool_userdata_set() in such cases.
00454  * @warning More generally, the key and the data to be attached to the
00455  *       pool should have a life span at least as long as the pool itself.
00456  *
00457  */
00458 APR_DECLARE(apr_status_t) apr_pool_userdata_setn(
00459     const void *data,
00460     const char *key,
00461     apr_status_t (*cleanup)(void *),
00462     apr_pool_t *pool);
00463 
00464 /**
00465  * Return the data associated with the current pool.
00466  * @param data The user data associated with the pool.
00467  * @param key The key for the data to retrieve
00468  * @param pool The current pool.
00469  */
00470 APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *key,
00471                                                 apr_pool_t *pool);
00472 
00473 
00474 /*
00475  * Cleanup
00476  *
00477  * Cleanups are performed in the reverse order they were registered.  That is:
00478  * Last In, First Out.  A cleanup function can safely allocate memory from
00479  * the pool that is being cleaned up. It can also safely register additional
00480  * cleanups which will be run LIFO, directly after the current cleanup
00481  * terminates.  Cleanups have to take caution in calling functions that
00482  * create subpools. Subpools, created during cleanup will NOT automatically
00483  * be cleaned up.  In other words, cleanups are to clean up after themselves.
00484  */
00485 
00486 /**
00487  * Register a function to be called when a pool is cleared or destroyed
00488  * @param p The pool register the cleanup with
00489  * @param data The data to pass to the cleanup function.
00490  * @param plain_cleanup The function to call when the pool is cleared
00491  *                      or destroyed
00492  * @param child_cleanup The function to call when a child process is about
00493  *                      to exec - this function is called in the child, obviously!
00494  */
00495 APR_DECLARE(void) apr_pool_cleanup_register(
00496     apr_pool_t *p,
00497     const void *data,
00498     apr_status_t (*plain_cleanup)(void *),
00499     apr_status_t (*child_cleanup)(void *));
00500 
00501 /**
00502  * Remove a previously registered cleanup function
00503  * @param p The pool remove the cleanup from
00504  * @param data The data to remove from cleanup
00505  * @param cleanup The function to remove from cleanup
00506  * @remarks For some strange reason only the plain_cleanup is handled by this
00507  *          function
00508  */
00509 APR_DECLARE(void) apr_pool_cleanup_kill(apr_pool_t *p, const void *data,
00510                                         apr_status_t (*cleanup)(void *));
00511 
00512 /**
00513  * Replace the child cleanup of a previously registered cleanup
00514  * @param p The pool of the registered cleanup
00515  * @param data The data of the registered cleanup
00516  * @param plain_cleanup The plain cleanup function of the registered cleanup
00517  * @param child_cleanup The function to register as the child cleanup
00518  */
00519 APR_DECLARE(void) apr_pool_child_cleanup_set(
00520     apr_pool_t *p,
00521     const void *data,
00522     apr_status_t (*plain_cleanup)(void *),
00523     apr_status_t (*child_cleanup)(void *));
00524 
00525 /**
00526  * Run the specified cleanup function immediately and unregister it. Use
00527  * @a data instead of the data that was registered with the cleanup.
00528  * @param p The pool remove the cleanup from
00529  * @param data The data to remove from cleanup
00530  * @param cleanup The function to remove from cleanup
00531  */
00532 APR_DECLARE(apr_status_t) apr_pool_cleanup_run(
00533     apr_pool_t *p,
00534     void *data,
00535     apr_status_t (*cleanup)(void *));
00536 
00537 /**
00538  * An empty cleanup function
00539  * @param data The data to cleanup
00540  */
00541 APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data);
00542 
00543 /* Preparing for exec() --- close files, etc., but *don't* flush I/O
00544  * buffers, *don't* wait for subprocesses, and *don't* free any memory.
00545  */
00546 /**
00547  * Run all of the child_cleanups, so that any unnecessary files are
00548  * closed because we are about to exec a new program
00549  */
00550 APR_DECLARE(void) apr_pool_cleanup_for_exec(void);
00551 
00552 
00553 /**
00554  * @defgroup PoolDebug Pool Debugging functions.
00555  *
00556  * pools have nested lifetimes -- sub_pools are destroyed when the
00557  * parent pool is cleared.  We allow certain liberties with operations
00558  * on things such as tables (and on other structures in a more general
00559  * sense) where we allow the caller to insert values into a table which
00560  * were not allocated from the table's pool.  The table's data will
00561  * remain valid as long as all the pools from which its values are
00562  * allocated remain valid.
00563  *
00564  * For example, if B is a sub pool of A, and you build a table T in
00565  * pool B, then it's safe to insert data allocated in A or B into T
00566  * (because B lives at most as long as A does, and T is destroyed when
00567  * B is cleared/destroyed).  On the other hand, if S is a table in
00568  * pool A, it is safe to insert data allocated in A into S, but it
00569  * is *not safe* to insert data allocated from B into S... because
00570  * B can be cleared/destroyed before A is (which would leave dangling
00571  * pointers in T's data structures).
00572  *
00573  * In general we say that it is safe to insert data into a table T
00574  * if the data is allocated in any ancestor of T's pool.  This is the
00575  * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor
00576  * relationships for all data inserted into tables.  APR_POOL_DEBUG also
00577  * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other
00578  * folks to implement similar restrictions for their own data
00579  * structures.
00580  *
00581  * However, sometimes this ancestor requirement is inconvenient --
00582  * sometimes we're forced to create a sub pool (such as through
00583  * apr_sub_req_lookup_uri), and the sub pool is guaranteed to have
00584  * the same lifetime as the parent pool.  This is a guarantee implemented
00585  * by the *caller*, not by the pool code.  That is, the caller guarantees
00586  * they won't destroy the sub pool individually prior to destroying the
00587  * parent pool.
00588  *
00589  * In this case the caller must call apr_pool_join() to indicate this
00590  * guarantee to the APR_POOL_DEBUG code.  There are a few examples spread
00591  * through the standard modules.
00592  *
00593  * These functions are only implemented when #APR_POOL_DEBUG is set.
00594  *
00595  * @{
00596  */
00597 #if APR_POOL_DEBUG || defined(DOXYGEN)
00598 /**
00599  * Guarantee that a subpool has the same lifetime as the parent.
00600  * @param p The parent pool
00601  * @param sub The subpool
00602  */
00603 APR_DECLARE(void) apr_pool_join(apr_pool_t *p, apr_pool_t *sub);
00604 
00605 /**
00606  * Find a pool from something allocated in it.
00607  * @param mem The thing allocated in the pool
00608  * @return The pool it is allocated in
00609  */
00610 APR_DECLARE(apr_pool_t *) apr_pool_find(const void *mem);
00611 
00612 /**
00613  * Report the number of bytes currently in the pool
00614  * @param p The pool to inspect
00615  * @param recurse Recurse/include the subpools' sizes
00616  * @return The number of bytes
00617  */
00618 APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, int recurse);
00619 
00620 /**
00621  * Lock a pool
00622  * @param pool The pool to lock
00623  * @param flag  The flag
00624  */
00625 APR_DECLARE(void) apr_pool_lock(apr_pool_t *pool, int flag);
00626 
00627 /* @} */
00628 
00629 #else /* APR_POOL_DEBUG or DOXYGEN */
00630 
00631 #ifdef apr_pool_join
00632 #undef apr_pool_join
00633 #endif
00634 #define apr_pool_join(a,b)
00635 
00636 #ifdef apr_pool_lock
00637 #undef apr_pool_lock
00638 #endif
00639 #define apr_pool_lock(pool, lock)
00640 
00641 #endif /* APR_POOL_DEBUG or DOXYGEN */
00642 
00643 /** @} */
00644 
00645 #ifdef __cplusplus
00646 }
00647 #endif
00648 
00649 #endif /* !APR_POOLS_H */

Generated on Tue May 10 04:16:53 2005 for Apache Portable Runtime by  doxygen 1.3.9.1