<!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>