apr_pools.h

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

Generated on Mon Nov 26 11:23:52 2007 for Apache Portable Runtime by  doxygen 1.5.2