apr__pools_8h-source.html

apr函数库使用手册

00160 <span class="comment">/**</span>
00161 <span class="comment"> * Tear down all of the internal structures required to use pools</span>
00162 <span class="comment"> * @remark Programs do NOT need to call this directly.  APR will call this</span>
00163 <span class="comment"> *      automatically from apr_terminate.</span>
00164 <span class="comment"> * @internal</span>
00165 <span class="comment"> */</span>
00166 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_terminate(<span class="keywordtype">void</span>);
00167 
00168 
00169 <span class="comment">/*</span>
00170 <span class="comment"> * Pool creation/destruction</span>
00171 <span class="comment"> */</span>
00172 
00173 #include "apr_allocator.h"
00174 <span class="comment"></span>
00175 <span class="comment">/**</span>
00176 <span class="comment"> * Create a new pool.</span>
00177 <span class="comment"> * @param newpool The pool we have just created.</span>
00178 <span class="comment"> * @param parent The parent pool.  If this is NULL, the new pool is a root</span>
00179 <span class="comment"> *        pool.  If it is non-NULL, the new pool will inherit all</span>
00180 <span class="comment"> *        of its parent pool's attributes, except the apr_pool_t will</span>
00181 <span class="comment"> *        be a sub-pool.</span>
00182 <span class="comment"> * @param abort_fn A function to use if the pool cannot allocate more memory.</span>
00183 <span class="comment"> * @param allocator The allocator to use with the new pool.  If NULL the</span>
00184 <span class="comment"> *        allocator of the parent pool will be used.</span>
00185 <span class="comment"> */</span>
00186 APR_DECLARE(apr_status_t) apr_pool_create_ex(apr_pool_t **newpool,
00187                                              apr_pool_t *parent,
00188                                              apr_abortfunc_t abort_fn,
00189                                              apr_allocator_t *allocator);
00190 <span class="comment"></span>
00191 <span class="comment">/**</span>
00192 <span class="comment"> * Debug version of apr_pool_create_ex.</span>
00193 <span class="comment"> * @param newpool @see apr_pool_create.</span>
00194 <span class="comment"> * @param parent @see apr_pool_create.</span>
00195 <span class="comment"> * @param abort_fn @see apr_pool_create.</span>
00196 <span class="comment"> * @param allocator @see apr_pool_create.</span>
00197 <span class="comment"> * @param file_line Where the function is called from.</span>
00198 <span class="comment"> *        This is usually APR_POOL__FILE_LINE__.</span>
00199 <span class="comment"> * @remark Only available when APR_POOL_DEBUG is defined.</span>
00200 <span class="comment"> *         Call this directly if you have you apr_pool_create_ex</span>
00201 <span class="comment"> *         calls in a wrapper function and wish to override</span>
00202 <span class="comment"> *         the file_line argument to reflect the caller of</span>
00203 <span class="comment"> *         your wrapper function.  If you do not have</span>
00204 <span class="comment"> *         apr_pool_create_ex in a wrapper, trust the macro</span>
00205 <span class="comment"> *         and don't call apr_pool_create_ex_debug directly.</span>
00206 <span class="comment"> */</span>
00207 APR_DECLARE(apr_status_t) apr_pool_create_ex_debug(apr_pool_t **newpool,
00208                                                    apr_pool_t *parent,
00209                                                    apr_abortfunc_t abort_fn,
00210                                                    apr_allocator_t *allocator,
00211                                                    const <span class="keywordtype">char</span> *file_line);
00212 
00213 #if APR_POOL_DEBUG
00214 #define apr_pool_create_ex(newpool, parent, abort_fn, allocator)  \
00215     apr_pool_create_ex_debug(newpool, parent, abort_fn, allocator, \
00216                              APR_POOL__FILE_LINE__)
00217 #endif
00218 <span class="comment"></span>
00219 <span class="comment">/**</span>
00220 <span class="comment"> * Create a new pool.</span>
00221 <span class="comment"> * @param newpool The pool we have just created.</span>
00222 <span class="comment"> * @param parent The parent pool.  If this is NULL, the new pool is a root</span>
00223 <span class="comment"> *        pool.  If it is non-NULL, the new pool will inherit all</span>
00224 <span class="comment"> *        of its parent pool's attributes, except the apr_pool_t will</span>
00225 <span class="comment"> *        be a sub-pool.</span>
00226 <span class="comment"> */</span>
00227 #if defined(DOXYGEN)
00228 APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool,
00229                                           apr_pool_t *parent);
00230 #else
00231 #if APR_POOL_DEBUG
00232 #define apr_pool_create(newpool, parent) \
00233     apr_pool_create_ex_debug(newpool, parent, NULL, NULL, \
00234                              APR_POOL__FILE_LINE__)
00235 #else
00236 #define apr_pool_create(newpool, parent) \
00237     apr_pool_create_ex(newpool, parent, NULL, NULL)
00238 #endif
00239 #endif
00240 <span class="comment"></span>
00241 <span class="comment">/**</span>
00242 <span class="comment"> * Find the pools allocator</span>
00243 <span class="comment"> * @param pool The pool to get the allocator from.</span>
00244 <span class="comment"> */</span>
00245 APR_DECLARE(apr_allocator_t *) apr_pool_allocator_get(apr_pool_t *pool);
00246 <span class="comment"></span>
00247 <span class="comment">/**</span>
00248 <span class="comment"> * Clear all memory in the pool and run all the cleanups. This also destroys all</span>
00249 <span class="comment"> * subpools.</span>
00250 <span class="comment"> * @param p The pool to clear</span>
00251 <span class="comment"> * @remark This does not actually free the memory, it just allows the pool</span>
00252 <span class="comment"> *         to re-use this memory for the next allocation.</span>
00253 <span class="comment"> * @see apr_pool_destroy()</span>
00254 <span class="comment"> */</span>
00255 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_clear(apr_pool_t *p);
00256 <span class="comment"></span>
00257 <span class="comment">/**</span>
00258 <span class="comment"> * Debug version of apr_pool_clear.</span>
00259 <span class="comment"> * @param p See: apr_pool_clear.</span>
00260 <span class="comment"> * @param file_line Where the function is called from.</span>
00261 <span class="comment"> *        This is usually APR_POOL__FILE_LINE__.</span>
00262 <span class="comment"> * @remark Only available when APR_POOL_DEBUG is defined.</span>
00263 <span class="comment"> *         Call this directly if you have you apr_pool_clear</span>
00264 <span class="comment"> *         calls in a wrapper function and wish to override</span>
00265 <span class="comment"> *         the file_line argument to reflect the caller of</span>
00266 <span class="comment"> *         your wrapper function.  If you do not have</span>
00267 <span class="comment"> *         apr_pool_clear in a wrapper, trust the macro</span>
00268 <span class="comment"> *         and don't call apr_pool_destroy_clear directly.</span>
00269 <span class="comment"> */</span>
00270 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_clear_debug(apr_pool_t *p,
00271                                        const <span class="keywordtype">char</span> *file_line);
00272 
00273 #if APR_POOL_DEBUG
00274 #define apr_pool_clear(p) \
00275     apr_pool_clear_debug(p, APR_POOL__FILE_LINE__)
00276 #endif
00277 <span class="comment"></span>
00278 <span class="comment">/**</span>
00279 <span class="comment"> * Destroy the pool. This takes similar action as apr_pool_clear() and then</span>
00280 <span class="comment"> * frees all the memory.</span>
00281 <span class="comment"> * @param p The pool to destroy</span>
00282 <span class="comment"> * @remark This will actually free the memory</span>
00283 <span class="comment"> */</span>
00284 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_destroy(apr_pool_t *p);
00285 <span class="comment"></span>
00286 <span class="comment">/**</span>
00287 <span class="comment"> * Debug version of apr_pool_destroy.</span>
00288 <span class="comment"> * @param p See: apr_pool_destroy.</span>
00289 <span class="comment"> * @param file_line Where the function is called from.</span>
00290 <span class="comment"> *        This is usually APR_POOL__FILE_LINE__.</span>
00291 <span class="comment"> * @remark Only available when APR_POOL_DEBUG is defined.</span>
00292 <span class="comment"> *         Call this directly if you have you apr_pool_destroy</span>
00293 <span class="comment"> *         calls in a wrapper function and wish to override</span>
00294 <span class="comment"> *         the file_line argument to reflect the caller of</span>
00295 <span class="comment"> *         your wrapper function.  If you do not have</span>
00296 <span class="comment"> *         apr_pool_destroy in a wrapper, trust the macro</span>
00297 <span class="comment"> *         and don't call apr_pool_destroy_debug directly.</span>
00298 <span class="comment"> */</span>
00299 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_destroy_debug(apr_pool_t *p,
00300                                          const <span class="keywordtype">char</span> *file_line);
00301 
00302 #if APR_POOL_DEBUG
00303 #define apr_pool_destroy(p) \
00304     apr_pool_destroy_debug(p, APR_POOL__FILE_LINE__)
00305 #endif
00306 
00307 
00308 <span class="comment">/*</span>
00309 <span class="comment"> * Memory allocation</span>
00310 <span class="comment"> */</span>
00311 <span class="comment"></span>
00312 <span class="comment">/**</span>
00313 <span class="comment"> * Allocate a block of memory from a pool</span>
00314 <span class="comment"> * @param p The pool to allocate from</span>
00315 <span class="comment"> * @param size The amount of memory to allocate</span>
00316 <span class="comment"> * @return The allocated memory</span>
00317 <span class="comment"> */</span>
00318 APR_DECLARE(<span class="keywordtype">void</span> *) apr_palloc(apr_pool_t *p, apr_size_t size);
00319 <span class="comment"></span>
00320 <span class="comment">/**</span>
00321 <span class="comment"> * Debug version of apr_palloc</span>
00322 <span class="comment"> * @param p See: apr_palloc</span>
00323 <span class="comment"> * @param size See: apr_palloc</span>
00324 <span class="comment"> * @param file_line Where the function is called from.</span>
00325 <span class="comment"> *        This is usually APR_POOL__FILE_LINE__.</span>