Apache Portable Runtime

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