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