00001 /* Copyright 2000-2004 The Apache Software Foundation -00002 * -00003 * Licensed under the Apache License, Versio= n 2.0 (the "License"); -00004 * you may not use this file except in compl= iance with the License. -00005 * You may obtain a copy of the License at -00006 * -00007 * http://www.apache.org/licenses/LICENS= E-2.0 -00008 * -00009 * Unless required by applicable law or agre= ed to in writing, software -00010 * distributed under the License is distribu= ted on an "AS IS" BASIS, -00011 * WITHOUT WARRANTIES OR CONDITIONS OF ANY K= IND, either express or implied. -00012 * See the License for the specific language= governing permissions and -00013 * limitations under the License. -00014 */ -00015=20 -00016 #ifndef APR_POOLS_H -00017 #de= fine 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 tr= ack of EVERYTHING so that -00026 * it can be explicitly freed later (a funda= mentally 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 th= ere 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-trans= action apr_pool_t without fear, -00033 * and without thinking too hard about it ei= ther. -00034 */ -00035=20 -00036 #include "apr.h" -00037 #include "apr_errno.h" -00038 #include "apr_general.h" /* for= APR_STRINGIFY */ -00= 039 #define APR_WANT_MEMFUNC /**< for no good reason? */ -00040 #include "apr_want.h" -00041=20 -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_po= ol_t apr_pool_t; -00054=20 -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 th= e data type. -00061 * -00062 * APR_POOL_DECLARE_ACCESSOR() is used in a = header file to declare the -00063 * accessor function. A typical usage and re= sult would be: -00064 * <pre> -00065 * APR_POOL_DECLARE_ACCESSOR(file); -00066 * becomes: -00067 * APR_DECLARE(apr_pool_t *) apr_file_poo= l_get(apr_file_t *ob); -00068 * </pre> -00069 * @remark Doxygen unwraps this macro (via d= oxygen.conf) to provide -00070 * actual help for each specific occurance o= f apr_foo_pool_get. -00071 * @remark the linkage is specified for APR.= It would be possible to expand -00072 * the macros to support other linkage= s=2E -00073 */ -00074 #define APR_POOL_DECLARE_ACCESSO= R(type) \ -00075 APR_DECLARE(apr_pool_t *) apr_##typ= e##_pool_get \ -00076 (const apr_##type##_t *the##typ= e) -00077 -00078 /** -00079 * Implementation helper macro to provide ap= r_foo_pool_get()s. -00080 * -00081 * In the implementation, the APR_POOL_IMPLE= MENT_ACCESSOR() is used to -00082 * actually define the function. It assumes = the field is named "pool". -00083 */ -00084 #define APR_POOL_IMPLEMENT_ACCES= SOR(type) \ -00085 APR_DECLARE(apr_pool_t *) apr_##typ= e##_pool_get \ -00086 (const apr_##type##_t *the#= #type) \ -00087 { return the##type->pool; }<= /span> -00088 -00089 -00090 /** -00091 * Pool debug levels -00092 * -00093 * <pre> -00094 * | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | -00095 * --------------------------------- -00096 * | | | | | | | | x | Genera= l debug code enabled (useful in -00097 * combin= ation with --with-efence). -00098 * -00099 * | | | | | | | x | | Verbos= e output on stderr (report -00100 * CREATE= , CLEAR, DESTROY). -00101 * -00102 * | | | | x | | | | | Verbos= e output on stderr (report -00103 * PALLOC= , PCALLOC). -00104 * -00105 * | | | | | | x | | | Lifeti= me checking. On each use of a -00106 * pool, = check its lifetime. If the pool -00107 * is out= of scope, abort(). -00108 * In com= bination with the verbose flag -00109 * above,= it will output LIFE in such an -00110 * event = prior to aborting. -00111 * -00112 * | | | | | x | | | | Pool o= wner checking. On each use of a -00113 * pool, = check if the current thread is the -00114 * pools = owner. If not, abort(). In -00115 * combin= ation with the verbose flag above, -00116 * it wil= l output OWNER in such an event -00117 * prior = to aborting. Use the debug -00118 * functi= on apr_pool_owner_set() to switch -00119 * a pool= s ownership. -00120 * -00121 * When no debug level was specified, assume= general debug mode. -00122 * If level 0 was specified, debugging is sw= itched off -00123 * </pre> -00124 */ -00125 #if defined(APR_POOL_DEBUG) -00126 /* If AP= R_POOL_DEBUG is blank, we get 1; if it is a number, we get -1. */ -00127 #if (APR_POOL_DEBUG - APR_POOL_DEBUG -1= =3D=3D 1) -00128 #un= def APR_POOL_DEBUG -00129 #de= fine APR_POOL_DEBUG 1 -00130 #en= dif -00131 #el= se -00132 #define APR_POOL_DEBUG 0 -00133 #en= dif -00134 -00135 /** the place in the code where the particul= ar function was called */ -00136 #define APR_POOL__FILE_LINE__ __= FILE__ ":" APR_STRINGIFY(__LINE__) -00137 -00138=20 -00139 -00140 /** A function that is called when allocatio= n fails. */ -00141 typedef int (*apr_abortfunc_t)(int retcode); -00142=20 -00143 /* -00144 * APR memory structure manipulators (pools,= tables, and arrays). -00145 */ -00146=20 -00147 /* -00148 * Initialization -00149 */ -00150 -00151 /** -00152 * Setup all of the internal structures requ= ired 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(ap= r_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_termin= ate(void); -00166=20 +

apr_pools.h

Go to the documentation= of this file.

00001 /* Copyright 2000-2005 The Apache Software Foundation or its licensors, a=
s
+00002  * applicable.
+00003  *
+00004  * Licensed under the Apache License, Versio=
n 2.0 (the "License");
+00005  * you may not use this file except in compl=
iance with the License.
+00006  * You may obtain a copy of the License at
+00007  *
+00008  *     http://www.apache.org/licenses/LICENS=
E-2.0
+00009  *
+00010  * Unless required by applicable law or agre=
ed to in writing, software
+00011  * distributed under the License is distribu=
ted on an "AS IS" BASIS,
+00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY K=
IND, either express or implied.
+00013  * See the License for the specific language=
 governing permissions and
+00014  * limitations under the License.
+00015  */
+00016=20
+00017 #ifndef APR_POOLS_H
+00018 #de=
fine 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 tr=
ack of EVERYTHING so that
+00027  * it can be explicitly freed later (a funda=
mentally 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 th=
ere 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-trans=
action apr_pool_t without fear,
+00034  * and without thinking too hard about it ei=
ther.
+00035  */
+00036=20
+00037 #include "apr.h"
+00038 #include "apr_errno.h"
+00039 #include "apr_general.h" /* for=
 APR_STRINGIFY */
+00=
040 #define APR_WANT_MEMFUNC /**< for no good reason? */
+00041 #include "apr_want.h"
+00042=20
+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_po=
ol_t apr_pool_t;
+00055=20
+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 th=
e data type.
+00062  *
+00063  * APR_POOL_DECLARE_ACCESSOR() is used in a =
header file to declare the
+00064  * accessor function. A typical usage and re=
sult would be:
+00065  * <pre>
+00066  *    APR_POOL_DECLARE_ACCESSOR(file);
+00067  * becomes:
+00068  *    APR_DECLARE(apr_pool_t *) apr_file_poo=
l_get(apr_file_t *ob);
+00069  * </pre>
+00070  * @remark Doxygen unwraps this macro (via d=
oxygen.conf) to provide 
+00071  * actual help for each specific occurance o=
f apr_foo_pool_get.
+00072  * @remark the linkage is specified for APR.=
 It would be possible to expand
+00073  *       the macros to support other linkage=
s=2E
+00074  */
+00075 #define APR_POOL_DECLARE_ACCESSO=
R(type) \
+00076     APR_DECLARE(apr_pool_t *) apr_##typ=
e##_pool_get \
+00077         (const apr_##type##_t *the##typ=
e)
+00078 
+00079 /** 
+00080  * Implementation helper macro to provide ap=
r_foo_pool_get()s.
+00081  *
+00082  * In the implementation, the APR_POOL_IMPLE=
MENT_ACCESSOR() is used to
+00083  * actually define the function. It assumes =
the field is named "pool".
+00084  */
+00085 #define APR_POOL_IMPLEMENT_ACCES=
SOR(type) \
+00086     APR_DECLARE(apr_pool_t *) apr_##typ=
e##_pool_get \
+00087             (const apr_##type##_t *the#=
#type) \
+00088         { return the##type->pool; }<=
/span>
+00089 
+00090 
+00091 /**
+00092  * Pool debug levels
+00093  *
+00094  * <pre>
+00095  * | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
+00096  * ---------------------------------
+00097  * |   |   |   |   |   |   |   | x |  Genera=
l debug code enabled (useful in
+00098  *                                    combin=
ation with --with-efence).
+00099  *
+00100  * |   |   |   |   |   |   | x |   |  Verbos=
e output on stderr (report
+00101  *                                    CREATE=
, CLEAR, DESTROY).
+00102  *
+00103  * |   |   |   | x |   |   |   |   |  Verbos=
e output on stderr (report
+00104  *                                    PALLOC=
, PCALLOC).
+00105  *
+00106  * |   |   |   |   |   | x |   |   |  Lifeti=
me checking. On each use of a
+00107  *                                    pool, =
check its lifetime.  If the pool
+00108  *                                    is out=
 of scope, abort().
+00109  *                                    In com=
bination with the verbose flag
+00110  *                                    above,=
 it will output LIFE in such an
+00111  *                                    event =
prior to aborting.
+00112  *
+00113  * |   |   |   |   | x |   |   |   |  Pool o=
wner checking.  On each use of a
+00114  *                                    pool, =
check if the current thread is the
+00115  *                                    pools =
owner.  If not, abort().  In
+00116  *                                    combin=
ation with the verbose flag above,
+00117  *                                    it wil=
l output OWNER in such an event
+00118  *                                    prior =
to aborting.  Use the debug
+00119  *                                    functi=
on apr_pool_owner_set() to switch
+00120  *                                    a pool=
s ownership.
+00121  *
+00122  * When no debug level was specified, assume=
 general debug mode.
+00123  * If level 0 was specified, debugging is sw=
itched off
+00124  * </pre>
+00125  */
+00126 #if defined(APR_POOL_DEBUG)
+00127 /* If AP=
R_POOL_DEBUG is blank, we get 1; if it is a number, we get -1. */
+00128 #if (APR_POOL_DEBUG - APR_POOL_DEBUG -1=
 =3D=3D 1)
+00129 #un=
def APR_POOL_DEBUG
+00130 #de=
fine APR_POOL_DEBUG 1
+00131 #en=
dif
+00132 #el=
se
+00133 #define APR_POOL_DEBUG 0
+00134 #en=
dif
+00135 
+00136 /** the place in the code where the particul=
ar function was called */
+00137 #define APR_POOL__FILE_LINE__ __=
FILE__ ":" APR_STRINGIFY(__LINE__)
+00138 
+00139=20
+00140 
+00141 /** A function that is called when allocatio=
n fails. */
+00142 typedef int (*apr_abortfunc_t)(=
int retcode);
+00143=20
+00144 /*
+00145  * APR memory structure manipulators (pools,=
 tables, and arrays).
+00146  */
+00147=20
+00148 /*
+00149  * Initialization
+00150  */
+00151 
+00152 /**
+00153  * Setup all of the internal structures requ=
ired 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_termin=
ate(void);
 00167=20
-00168 /*
-00169  * Pool creation/destruction
-00170  */
-00171=20
-00172 #include "apr_allocator.h"
-00173 
-00174 /**
-00175  * Create a new pool.
-00176  * @param newpool The pool we have just crea=
ted.
-00177  * @param parent The parent pool.  If this i=
s 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, e=
xcept 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 wit=
h the new pool.  If NULL the
-00183  *        allocator of the parent pool will =
be used.
-00184  */
-00185 APR_DECLARE(ap=
r_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 ca=
lled from.
-00197  *        This is usually APR_POOL__FILE_LIN=
E__.
-00198  * @remark Only available when APR_POOL_DEBU=
G is defined.
-00199  *         Call this directly if you have yo=
u apr_pool_create_ex
-00200  *         calls in a wrapper function and w=
ish 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(ap=
r_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool,
-00207                                                    apr_pool_t *paren=
t,
-00208                                                    apr_abortfunc_t abort_fn,
-00209                                                    apr_allocator_t *allocator,
-00210                                                    const char *file_line);
-00211=20
-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 crea=
ted.
-00221  * @param parent The parent pool.  If this i=
s 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, e=
xcept the apr_pool_t will
-00224  *        be a sub-pool.
-00225  */
-00226 #if defined(DOXYGEN)
-00227 APR_DECLARE(ap=
r_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
+00168=20
+00169 /*
+00170  * Pool creation/destruction
+00171  */
+00172=20
+00173 #include "apr_allocator.h"
+00174 
+00175 /**
+00176  * Create a new pool.
+00177  * @param newpool The pool we have just crea=
ted.
+00178  * @param parent The parent pool.  If this i=
s 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, e=
xcept 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 wit=
h 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_f=
n,
+00189                                              apr_allocator_t *alloca=
tor);
+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 ca=
lled from.
+00198  *        This is usually APR_POOL__FILE_LIN=
E__.
+00199  * @remark Only available when APR_POOL_DEBU=
G is defined.
+00200  *         Call this directly if you have yo=
u apr_pool_create_ex
+00201  *         calls in a wrapper function and w=
ish 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 **newp=
ool,
+00208                                                    apr_pool_t *paren=
t,
+00209                                                    apr_abortfunc_t a=
bort_fn,
+00210                                                    apr_allocator_t *=
allocator,
+00211                                                    const char *file_line);
+00212=20
+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 crea=
ted.
+00222  * @param parent The parent pool.  If this i=
s 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, e=
xcept 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 
-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 m=
emory, it just allows the pool
-00251  *         to re-use this memory for the nex=
t 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 ca=
lled from.
-00260  *        This is usually APR_POOL__FILE_LIN=
E__.
-00261  * @remark Only available when APR_POOL_DEBU=
G is defined.
-00262  *         Call this directly if you have yo=
u apr_pool_clear
-00263  *         calls in a wrapper function and w=
ish 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, trus=
t the macro
-00267  *         and don't call apr_pool_destroy_c=
lear directly.
-00268  */
-00269 APR_DECLARE(void) apr_pool_clear_=
debug(apr_pool_t *p,
-00270                                        const char *file_line);
-00271=20
-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 acti=
on 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 memor=
y
-00282  */
-00283 APR_DECLARE(void) apr_pool_destro=
y(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 ca=
lled from.
-00289  *        This is usually APR_POOL__FILE_LIN=
E__.
-00290  * @remark Only available when APR_POOL_DEBU=
G is defined.
-00291  *         Call this directly if you have yo=
u apr_pool_destroy
-00292  *         calls in a wrapper function and w=
ish 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, tr=
ust the macro
-00296  *         and don't call apr_pool_destroy_d=
ebug directly.
-00297  */
-00298 APR_DECLARE(void) apr_pool_destro=
y_debug(apr_pool_t *p,
-00299                                          const char *file_line);
-00300=20
-00301 #if APR_POOL_DEBUG
-00302 #define apr_pool_destroy(p) \
-00303     apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__)
-00304 #endif
-00305=20
+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 *po=
ol);
+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 m=
emory, it just allows the pool
+00252  *         to re-use this memory for the nex=
t 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 ca=
lled from.
+00261  *        This is usually APR_POOL__FILE_LIN=
E__.
+00262  * @remark Only available when APR_POOL_DEBU=
G is defined.
+00263  *         Call this directly if you have yo=
u apr_pool_clear
+00264  *         calls in a wrapper function and w=
ish 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, trus=
t the macro
+00268  *         and don't call apr_pool_destroy_c=
lear directly.
+00269  */
+00270 APR_DECLARE(void) apr_pool_clear_=
debug(apr_pool_t *p,
+00271                                        const char *file_line);
+00272=20
+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 acti=
on 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 memor=
y
+00283  */
+00284 APR_DECLARE(void) apr_pool_destro=
y(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 ca=
lled from.
+00290  *        This is usually APR_POOL__FILE_LIN=
E__.
+00291  * @remark Only available when APR_POOL_DEBU=
G is defined.
+00292  *         Call this directly if you have yo=
u apr_pool_destroy
+00293  *         calls in a wrapper function and w=
ish 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, tr=
ust the macro
+00297  *         and don't call apr_pool_destroy_d=
ebug directly.
+00298  */
+00299 APR_DECLARE(void) apr_pool_destro=
y_debug(apr_pool_t *p,
+00300                                          const char *file_line);
+00301=20
+00302 #if APR_POOL_DEBUG
+00303 #define apr_pool_destroy(p) \
+00304     apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__)
+00305 #endif
 00306=20
-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 alloc=
ate
-00315  * @return The allocated memory
-00316  */
-00317 APR_DECLARE(void *) apr_palloc(ap=
r_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 ca=
lled from.
-00324  *        This is usually APR_POOL__FILE_LIN=
E__.
-00325  * @return See: apr_palloc
-00326  */
-00327 APR_DECLARE(void *) apr_palloc_de=
bug(apr_pool_t *p, apr_size_t size,
-00328                                      const char *file_line);
-00329=20
-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 an=
d set all of the memory to 0
-00337  * @param p The pool to allocate from
-00338  * @param size The amount of memory to alloc=
ate
-00339  * @return The allocated memory
-00340  */
-00341 #if defined(DOXYGEN)
-00342 APR_DECLARE(void *) apr_pcalloc(a=
pr_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 ca=
lled from.
-00352  *        This is usually APR_POOL__FILE_LIN=
E__.
-00353  * @return See: apr_pcalloc
-00354  */
-00355 APR_DECLARE(void *) apr_pcalloc_d=
ebug(apr_pool_t *p, apr_size_t size,
-00356                                       const char *file_line);
-00357=20
-00358 #if APR_POOL_DEBUG
-00359 #define apr_pcalloc(p, size) \
-00360     apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__)
-00361 #endif
-00362=20
+00307=20
+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 alloc=
ate
+00316  * @return The allocated memory
+00317  */
+00318 APR_DECLARE(void *) apr_palloc(ap=
r_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 ca=
lled from.
+00325  *        This is usually APR_POOL__FILE_LIN=
E__.
+00326  * @return See: apr_palloc
+00327  */
+00328 APR_DECLARE(void *) apr_palloc_de=
bug(apr_pool_t *p, apr_size_t size,
+00329                                      const char *file_line);
+00330=20
+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 an=
d set all of the memory to 0
+00338  * @param p The pool to allocate from
+00339  * @param size The amount of memory to alloc=
ate
+00340  * @return The allocated memory
+00341  */
+00342 #if defined(DOXYGEN)
+00343 APR_DECLARE(void *) apr_pcalloc(a=
pr_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 ca=
lled from.
+00353  *        This is usually APR_POOL__FILE_LIN=
E__.
+00354  * @return See: apr_pcalloc
+00355  */
+00356 APR_DECLARE(void *) apr_pcalloc_d=
ebug(apr_pool_t *p, apr_size_t size,
+00357                                       const char *file_line);
+00358=20
+00359 #if APR_POOL_DEBUG
+00360 #define apr_pcalloc(p, size) \
+00361     apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__)
+00362 #endif
 00363=20
-00364 /*
-00365  * Pool Properties
-00366  */
-00367 
-00368 /**
-00369  * Set the function to be called when an all=
ocation 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 ex=
pect 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 th=
e specified pool.
-00381  * @param pool The pool for retrieving the a=
bort function.
-00382  * @return The abort function for the given =
pool.
-00383  */
-00384 APR_DECLARE(ap=
r_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 p=
arent 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 poo=
l 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, NU=
LL is considered an ancestor
-00398  *         of all pools.
-00399  */
-00400 APR_DECLARE(int) apr_pool_is_ance=
stor(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(ap=
r_pool_t *pool, const char *tag);
-00408=20
+00364=20
+00365 /*
+00366  * Pool Properties
+00367  */
+00368 
+00369 /**
+00370  * Set the function to be called when an all=
ocation 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 ex=
pect 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 th=
e specified pool.
+00382  * @param pool The pool for retrieving the a=
bort 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 p=
arent 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 poo=
l 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, NU=
LL is considered an ancestor
+00399  *         of all pools.
+00400  */
+00401 APR_DECLARE(int) apr_pool_is_ance=
stor(apr_pool_t *a, apr_pool_t *b);
+00402 
+00403 /**
+00404  * Tag a pool (give it a name)
+00405  * @param pool The pool to tag
+00406  * @param tag  The tag
+00407  */
+00408 APR_DECLARE(void) apr_pool_tag(ap=
r_pool_t *pool, const char *tag);
 00409=20
-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 p=
ool 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 a=
re taken to ensure that unique
-00427  *      keys are used for all of the userdat=
a 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.  Car=
eful namespace prefixing of
-00430  *      key names is a typical way to help e=
nsure this uniqueness.
-00431  *
-00432  */
-00433 APR_DECLARE(ap=
r_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(), ex=
cept that this version doesn't
-00446  *       make a copy of the key (this functi=
on is useful, for example, when
-00447  *       the key is a string literal)
-00448  * @warning This should NOT be used if the k=
ey could change addresses by
-00449  *       any means between the apr_pool_user=
data_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 th=
e _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 lea=
st as long as the pool itself.
-00456  *
-00457  */
-00458 APR_DECLARE(ap=
r_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 curre=
nt pool.
-00466  * @param data The user data associated with=
 the pool.
-00467  * @param key The key for the data to retrie=
ve
-00468  * @param pool The current pool.
-00469  */
-00470 APR_DECLARE(ap=
r_status_t) apr_pool_userdata_get(void **data, const char *key,
-00471                                                 apr_pool_t *pool);
-00472=20
+00410=20
+00411 /*
+00412  * User data management
+00413  */
+00414 
+00415 /**
+00416  * Set the data associated with the current =
pool
+00417  * @param data The user data associated with=
 the pool.
+00418  * @param key The key to use for association=

+00419  * @param cleanup The cleanup program to use=
 to cleanup the data (NULL if none)
+00420  * @param pool The current pool
+00421  * @warning The data to be attached to the p=
ool should have a life span
+00422  *          at least as long as the pool it =
is being attached to.
+00423  *
+00424  *      Users of APR must take EXTREME care =
when choosing a key to
+00425  *      use for their data.  It is possible =
to accidentally overwrite
+00426  *      data by choosing a key that another =
part of the program is using.
+00427  *      Therefore it is advised that steps a=
re taken to ensure that unique
+00428  *      keys are used for all of the userdat=
a objects in a particular pool
+00429  *      (the same key in two different pools=
 or a pool and one of its
+00430  *      subpools is okay) at all times.  Car=
eful namespace prefixing of
+00431  *      key names is a typical way to help e=
nsure this uniqueness.
+00432  *
+00433  */
+00434 APR_DECLARE(apr_status_t) apr_pool_userdata_set(
+00435     const void *data,
+00436     const char *key,
+00437     apr_status_t (*cleanup)(void =
*),
+00438     apr_pool_t *pool);
+00439 
+00440 /**
+00441  * Set the data associated with the current =
pool
+00442  * @param data The user data associated with=
 the pool.
+00443  * @param key The key to use for association=

+00444  * @param cleanup The cleanup program to use=
 to cleanup the data (NULL if none)
+00445  * @param pool The current pool
+00446  * @note same as apr_pool_userdata_set(), ex=
cept that this version doesn't
+00447  *       make a copy of the key (this functi=
on is useful, for example, when
+00448  *       the key is a string literal)
+00449  * @warning This should NOT be used if the k=
ey could change addresses by
+00450  *       any means between the apr_pool_user=
data_setn() call and a
+00451  *       subsequent apr_pool_userdata_get() =
on that key, such as if a
+00452  *       static string is used as a userdata=
 key in a DSO and the DSO could
+00453  *       be unloaded and reloaded between th=
e _setn() and the _get().  You
+00454  *       MUST use apr_pool_userdata_set() in=
 such cases.
+00455  * @warning More generally, the key and the =
data to be attached to the
+00456  *       pool should have a life span at lea=
st as long as the pool itself.
+00457  *
+00458  */
+00459 APR_DECLARE(apr_status_t) apr_pool_userdata_setn(
+00460     const void *data,
+00461     const char *key,
+00462     apr_status_t (*cleanup)(void =
*),
+00463     apr_pool_t *pool);
+00464 
+00465 /**
+00466  * Return the data associated with the curre=
nt pool.
+00467  * @param data The user data associated with=
 the pool.
+00468  * @param key The key for the data to retrie=
ve
+00469  * @param pool The current pool.
+00470  */
+00471 APR_DECLARE(apr_status_t) apr_pool_userdata_get(void **data, const char *=
key,
+00472                                                 apr_pool_t *pool);
 00473=20
-00474 /*
-00475  * Cleanup
-00476  *
-00477  * Cleanups are performed in the reverse ord=
er they were registered.  That is:
-00478  * Last In, First Out.  A cleanup function c=
an 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 cautio=
n 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 p=
ool is cleared or destroyed
-00488  * @param p The pool register the cleanup wi=
th
-00489  * @param data The data to pass to the clean=
up 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 funct=
ion is called in the child, obviously!
-00494  */
-00495 APR_DECLARE(void) apr_pool_cleanu=
p_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 fu=
nction
-00503  * @param p The pool remove the cleanup from=

-00504  * @param data The data to remove from clean=
up
-00505  * @param cleanup The function to remove fro=
m cleanup
-00506  * @remarks For some strange reason only the=
 plain_cleanup is handled by this
-00507  *          function
-00508  */
-00509 APR_DECLARE(void) apr_pool_cleanu=
p_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 clean=
up
-00515  * @param data The data of the registered cl=
eanup
-00516  * @param plain_cleanup The plain cleanup fu=
nction of the registered cleanup
-00517  * @param child_cleanup The function to regi=
ster 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 immedi=
ately and unregister it. Use
-00527  * @a data instead of the data that was regi=
stered with the cleanup.
-00528  * @param p The pool remove the cleanup from=

-00529  * @param data The data to remove from clean=
up
-00530  * @param cleanup The function to remove fro=
m cleanup
-00531  */
-00532 APR_DECLARE(ap=
r_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(vo=
id *data);
-00542=20
-00543 /* Preparing for exec() --- close files, etc=
., but *don't* flush I/O
-00544  * buffers, *don't* wait for subprocesses, a=
nd *don't* free any memory.
-00545  */
-00546 /**
-00547  * Run all of the child_cleanups, so that an=
y unnecessary files are
-00548  * closed because we are about to exec a new=
 program
-00549  */
-00550 APR_DECLARE(void) apr_pool_cleanu=
p_for_exec(void);
-00551=20
-00552 
-00553 /**
-00554  * @defgroup PoolDebug Pool Debugging functi=
ons.
-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 st=
ructures in a more general
-00559  * sense) where we allow the caller to inser=
t 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 fro=
m 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 all=
ocated in A or B into T
-00566  * (because B lives at most as long as A doe=
s, and T is destroyed when
-00567  * B is cleared/destroyed).  On the other ha=
nd, if S is a table in
-00568  * pool A, it is safe to insert data allocat=
ed in A into S, but it
-00569  * is *not safe* to insert data allocated fr=
om B into S... because
-00570  * B can be cleared/destroyed before A is (w=
hich would leave dangling
-00571  * pointers in T's data structures).
-00572  *
-00573  * In general we say that it is safe to inse=
rt 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 wo=
rks -- it tests these ancestor
-00576  * relationships for all data inserted into =
tables.  APR_POOL_DEBUG also
-00577  * provides tools (apr_pool_find, and apr_po=
ol_is_ancestor) for other
-00578  * folks to implement similar restrictions f=
or their own data
-00579  * structures.
-00580  *
-00581  * However, sometimes this ancestor requirem=
ent is inconvenient --
-00582  * sometimes we're forced to create a sub po=
ol (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.  Th=
is is a guarantee implemented
-00585  * by the *caller*, not by the pool code.  T=
hat is, the caller guarantees
-00586  * they won't destroy the sub pool individua=
lly prior to destroying the
-00587  * parent pool.
-00588  *
-00589  * In this case the caller must call apr_poo=
l_join() to indicate this
-00590  * guarantee to the APR_POOL_DEBUG code.  Th=
ere 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 lif=
etime as the parent.
-00600  * @param p The parent pool
-00601  * @param sub The subpool
-00602  */
-00603 APR_DECLARE(void) apr_pool_join(a=
pr_pool_t *p, apr_pool_t *sub);
-00604 
-00605 /**
-00606  * Find a pool from something allocated in i=
t=2E
-00607  * @param mem The thing allocated in the poo=
l
-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 t=
he pool
-00614  * @param p The pool to inspect
-00615  * @param recurse Recurse/include the subpoo=
ls' 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(a=
pr_pool_t *pool, int flag);
-00626=20
-00627 /* @} */
-00628=20
-00629 #else /* APR_POOL_DEBUG or DOXYGEN */
-00630=20
-00631 #ifdef apr_pool_join
-00632 #undef apr_pool_join
-00633 #endif
-00634 #define apr_pool_join(a,b)
-00635=20
-00636 #ifdef apr_pool_lock
-00637 #undef apr_pool_lock
-00638 #endif
-00639 #define apr_pool_lock(pool, lock)
-00640=20
-00641 #endif /* APR_POOL_DEBUG or DOXYGEN */
-00642 
-00643 /** @} */
-00644=20
-00645 #ifdef __cplusplus
-00646 }
-00647 #endif
-00648=20
-00649 #endif /* !APR_POOLS_H */
-

Generat= ed on Wed Sep 1 21:36:05 2004 for Apache Portable Runtime by +00474=20 +00475 /* +00476 * Cleanup +00477 * +00478 * Cleanups are performed in the reverse ord= er they were registered. That is: +00479 * Last In, First Out. A cleanup function c= an safely allocate memory from +00480 * the pool that is being cleaned up. It can= also safely register additional +00481 * cleanups which will be run LIFO, directly= after the current cleanup +00482 * terminates. Cleanups have to take cautio= n in calling functions that +00483 * create subpools. Subpools, created during= cleanup will NOT automatically +00484 * be cleaned up. In other words, cleanups = are to clean up after themselves. +00485 */ +00486 +00487 /** +00488 * Register a function to be called when a p= ool is cleared or destroyed +00489 * @param p The pool register the cleanup wi= th +00490 * @param data The data to pass to the clean= up function. +00491 * @param plain_cleanup The function to call= when the pool is cleared +00492 * or destroyed +00493 * @param child_cleanup The function to call= when a child process is about +00494 * to exec - this funct= ion is called in the child, obviously! +00495 */ +00496 APR_DECLARE(void) apr_pool_cleanu= p_register( +00497 apr_pool_t *p, +00498 const void *data, +00499 apr_status_t (*plain_cleanup)(void *), +00500 apr_status_t (*child_cleanup)(void *)); +00501 +00502 /** +00503 * Remove a previously registered cleanup fu= nction +00504 * @param p The pool remove the cleanup from= +00505 * @param data The data to remove from clean= up +00506 * @param cleanup The function to remove fro= m cleanup +00507 * @remarks For some strange reason only the= plain_cleanup is handled by this +00508 * function +00509 */ +00510 APR_DECLARE(void) apr_pool_cleanu= p_kill(apr_pool_t *p, const void *data, +00511 apr_status_t (*cleanup)(void *)); +00512 +00513 /** +00514 * Replace the child cleanup of a previously= registered cleanup +00515 * @param p The pool of the registered clean= up +00516 * @param data The data of the registered cl= eanup +00517 * @param plain_cleanup The plain cleanup fu= nction of the registered cleanup +00518 * @param child_cleanup The function to regi= ster as the child cleanup +00519 */ +00520 APR_DECLARE(void) apr_pool_child_= cleanup_set( +00521 apr_pool_t *p, +00522 const void *data, +00523 apr_status_t (*plain_cleanup)(void *), +00524 apr_status_t (*child_cleanup)(void *)); +00525 +00526 /** +00527 * Run the specified cleanup function immedi= ately and unregister it. Use +00528 * @a data instead of the data that was regi= stered with the cleanup. +00529 * @param p The pool remove the cleanup from= +00530 * @param data The data to remove from clean= up +00531 * @param cleanup The function to remove fro= m cleanup +00532 */ +00533 APR_DECLARE(apr_status_t) apr_pool_cleanup_run( +00534 apr_pool_t *p, +00535 void *data, +00536 apr_status_t (*cleanup)(void = *)); +00537 +00538 /** +00539 * An empty cleanup function +00540 * @param data The data to cleanup +00541 */ +00542 APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(void *data); +00543=20 +00544 /* Preparing for exec() --- close files, etc= ., but *don't* flush I/O +00545 * buffers, *don't* wait for subprocesses, a= nd *don't* free any memory. +00546 */ +00547 /** +00548 * Run all of the child_cleanups, so that an= y unnecessary files are +00549 * closed because we are about to exec a new= program +00550 */ +00551 APR_DECLARE(void) apr_pool_cleanu= p_for_exec(void); +00552=20 +00553 +00554 /** +00555 * @defgroup PoolDebug Pool Debugging functi= ons. +00556 * +00557 * pools have nested lifetimes -- sub_pools = are destroyed when the +00558 * parent pool is cleared. We allow certain= liberties with operations +00559 * on things such as tables (and on other st= ructures in a more general +00560 * sense) where we allow the caller to inser= t values into a table which +00561 * were not allocated from the table's pool.= The table's data will +00562 * remain valid as long as all the pools fro= m which its values are +00563 * allocated remain valid. +00564 * +00565 * For example, if B is a sub pool of A, and= you build a table T in +00566 * pool B, then it's safe to insert data all= ocated in A or B into T +00567 * (because B lives at most as long as A doe= s, and T is destroyed when +00568 * B is cleared/destroyed). On the other ha= nd, if S is a table in +00569 * pool A, it is safe to insert data allocat= ed in A into S, but it +00570 * is *not safe* to insert data allocated fr= om B into S... because +00571 * B can be cleared/destroyed before A is (w= hich would leave dangling +00572 * pointers in T's data structures). +00573 * +00574 * In general we say that it is safe to inse= rt data into a table T +00575 * if the data is allocated in any ancestor = of T's pool. This is the +00576 * basis on which the APR_POOL_DEBUG code wo= rks -- it tests these ancestor +00577 * relationships for all data inserted into = tables. APR_POOL_DEBUG also +00578 * provides tools (apr_pool_find, and apr_po= ol_is_ancestor) for other +00579 * folks to implement similar restrictions f= or their own data +00580 * structures. +00581 * +00582 * However, sometimes this ancestor requirem= ent is inconvenient -- +00583 * sometimes we're forced to create a sub po= ol (such as through [=2E.. 74 lines stripped ...]