apr__pools_8h-source.html

apr函数库使用手册

00326 <span class="comment"> * @return See: apr_palloc</span>
00327 <span class="comment"> */</span>
00328 APR_DECLARE(<span class="keywordtype">void</span> *) apr_palloc_debug(apr_pool_t *p, apr_size_t size,
00329                                      const <span class="keywordtype">char</span> *file_line);
00330 
00331 #if APR_POOL_DEBUG
00332 #define apr_palloc(p, size) \
00333     apr_palloc_debug(p, size, APR_POOL__FILE_LINE__)
00334 #endif
00335 <span class="comment"></span>
00336 <span class="comment">/**</span>
00337 <span class="comment"> * Allocate a block of memory from a pool and set all of the memory to 0</span>
00338 <span class="comment"> * @param p The pool to allocate from</span>
00339 <span class="comment"> * @param size The amount of memory to allocate</span>
00340 <span class="comment"> * @return The allocated memory</span>
00341 <span class="comment"> */</span>
00342 #if defined(DOXYGEN)
00343 APR_DECLARE(<span class="keywordtype">void</span> *) apr_pcalloc(apr_pool_t *p, apr_size_t size);
00344 #elif !APR_POOL_DEBUG
00345 #define apr_pcalloc(p, size) memset(apr_palloc(p, size), 0, size)
00346 #endif
00347 <span class="comment"></span>
00348 <span class="comment">/**</span>
00349 <span class="comment"> * Debug version of apr_pcalloc</span>
00350 <span class="comment"> * @param p See: apr_pcalloc</span>
00351 <span class="comment"> * @param size See: apr_pcalloc</span>
00352 <span class="comment"> * @param file_line Where the function is called from.</span>
00353 <span class="comment"> *        This is usually APR_POOL__FILE_LINE__.</span>
00354 <span class="comment"> * @return See: apr_pcalloc</span>
00355 <span class="comment"> */</span>
00356 APR_DECLARE(<span class="keywordtype">void</span> *) apr_pcalloc_debug(apr_pool_t *p, apr_size_t size,
00357                                       const <span class="keywordtype">char</span> *file_line);
00358 
00359 #if APR_POOL_DEBUG
00360 #define apr_pcalloc(p, size) \
00361     apr_pcalloc_debug(p, size, APR_POOL__FILE_LINE__)
00362 #endif
00363 
00364 
00365 <span class="comment">/*</span>
00366 <span class="comment"> * Pool Properties</span>
00367 <span class="comment"> */</span>
00368 <span class="comment"></span>
00369 <span class="comment">/**</span>
00370 <span class="comment"> * Set the function to be called when an allocation failure occurs.</span>
00371 <span class="comment"> * @remark If the program wants APR to exit on a memory allocation error,</span>
00372 <span class="comment"> *      then this function can be called to set the callback to use (for</span>
00373 <span class="comment"> *      performing cleanup and then exiting). If this function is not called,</span>
00374 <span class="comment"> *      then APR will return an error and expect the calling program to</span>
00375 <span class="comment"> *      deal with the error accordingly.</span>
00376 <span class="comment"> */</span>
00377 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_abort_set(apr_abortfunc_t abortfunc,
00378                                      apr_pool_t *pool);
00379 <span class="comment"></span>
00380 <span class="comment">/**</span>
00381 <span class="comment"> * Get the abort function associated with the specified pool.</span>
00382 <span class="comment"> * @param pool The pool for retrieving the abort function.</span>
00383 <span class="comment"> * @return The abort function for the given pool.</span>
00384 <span class="comment"> */</span>
00385 APR_DECLARE(apr_abortfunc_t) apr_pool_abort_get(apr_pool_t *pool);
00386 <span class="comment"></span>
00387 <span class="comment">/**</span>
00388 <span class="comment"> * Get the parent pool of the specified pool.</span>
00389 <span class="comment"> * @param pool The pool for retrieving the parent pool.</span>
00390 <span class="comment"> * @return The parent of the given pool.</span>
00391 <span class="comment"> */</span>
00392 APR_DECLARE(apr_pool_t *) apr_pool_parent_get(apr_pool_t *pool);
00393 <span class="comment"></span>
00394 <span class="comment">/**</span>
00395 <span class="comment"> * Determine if pool a is an ancestor of pool b</span>
00396 <span class="comment"> * @param a The pool to search</span>
00397 <span class="comment"> * @param b The pool to search for</span>
00398 <span class="comment"> * @return True if a is an ancestor of b, NULL is considered an ancestor</span>
00399 <span class="comment"> *         of all pools.</span>
00400 <span class="comment"> */</span>
00401 APR_DECLARE(<span class="keywordtype">int</span>) apr_pool_is_ancestor(apr_pool_t *a, apr_pool_t *b);
00402 <span class="comment"></span>
00403 <span class="comment">/**</span>
00404 <span class="comment"> * Tag a pool (give it a name)</span>
00405 <span class="comment"> * @param pool The pool to tag</span>
00406 <span class="comment"> * @param tag  The tag</span>
00407 <span class="comment"> */</span>
00408 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_tag(apr_pool_t *pool, const <span class="keywordtype">char</span> *tag);
00409 
00410 
00411 <span class="comment">/*</span>
00412 <span class="comment"> * User data management</span>
00413 <span class="comment"> */</span>
00414 <span class="comment"></span>
00415 <span class="comment">/**</span>
00416 <span class="comment"> * Set the data associated with the current pool</span>
00417 <span class="comment"> * @param data The user data associated with the pool.</span>
00418 <span class="comment"> * @param key The key to use for association</span>
00419 <span class="comment"> * @param cleanup The cleanup program to use to cleanup the data (NULL if none)</span>
00420 <span class="comment"> * @param pool The current pool</span>
00421 <span class="comment"> * @warning The data to be attached to the pool should have a life span</span>
00422 <span class="comment"> *          at least as long as the pool it is being attached to.</span>
00423 <span class="comment"> *</span>
00424 <span class="comment"> *      Users of APR must take EXTREME care when choosing a key to</span>
00425 <span class="comment"> *      use for their data.  It is possible to accidentally overwrite</span>
00426 <span class="comment"> *      data by choosing a key that another part of the program is using.</span>
00427 <span class="comment"> *      Therefore it is advised that steps are taken to ensure that unique</span>
00428 <span class="comment"> *      keys are used for all of the userdata objects in a particular pool</span>
00429 <span class="comment"> *      (the same key in two different pools or a pool and one of its</span>
00430 <span class="comment"> *      subpools is okay) at all times.  Careful namespace prefixing of</span>
00431 <span class="comment"> *      key names is a typical way to help ensure this uniqueness.</span>
00432 <span class="comment"> *</span>
00433 <span class="comment"> */</span>
00434 APR_DECLARE(apr_status_t) apr_pool_userdata_set(
00435     const <span class="keywordtype">void</span> *data,
00436     const <span class="keywordtype">char</span> *key,
00437     apr_status_t (*cleanup)(<span class="keywordtype">void</span> *),
00438     apr_pool_t *pool);
00439 <span class="comment"></span>
00440 <span class="comment">/**</span>
00441 <span class="comment"> * Set the data associated with the current pool</span>
00442 <span class="comment"> * @param data The user data associated with the pool.</span>
00443 <span class="comment"> * @param key The key to use for association</span>
00444 <span class="comment"> * @param cleanup The cleanup program to use to cleanup the data (NULL if none)</span>
00445 <span class="comment"> * @param pool The current pool</span>
00446 <span class="comment"> * @note same as apr_pool_userdata_set(), except that this version doesn't</span>
00447 <span class="comment"> *       make a copy of the key (this function is useful, for example, when</span>
00448 <span class="comment"> *       the key is a string literal)</span>
00449 <span class="comment"> * @warning This should NOT be used if the key could change addresses by</span>
00450 <span class="comment"> *       any means between the apr_pool_userdata_setn() call and a</span>
00451 <span class="comment"> *       subsequent apr_pool_userdata_get() on that key, such as if a</span>
00452 <span class="comment"> *       static string is used as a userdata key in a DSO and the DSO could</span>
00453 <span class="comment"> *       be unloaded and reloaded between the _setn() and the _get().  You</span>
00454 <span class="comment"> *       MUST use apr_pool_userdata_set() in such cases.</span>
00455 <span class="comment"> * @warning More generally, the key and the data to be attached to the</span>
00456 <span class="comment"> *       pool should have a life span at least as long as the pool itself.</span>
00457 <span class="comment"> *</span>
00458 <span class="comment"> */</span>
00459 APR_DECLARE(apr_status_t) apr_pool_userdata_setn(
00460     const <span class="keywordtype">void</span> *data,
00461     const <span class="keywordtype">char</span> *key,
00462     apr_status_t (*cleanup)(<span class="keywordtype">void</span> *),
00463     apr_pool_t *pool);
00464 <span class="comment"></span>
00465 <span class="comment">/**</span>
00466 <span class="comment"> * Return the data associated with the current pool.</span>
00467 <span class="comment"> * @param data The user data associated with the pool.</span>
00468 <span class="comment"> * @param key The key for the data to retrieve</span>
00469 <span class="comment"> * @param pool The current pool.</span>
00470 <span class="comment"> */</span>
00471 APR_DECLARE(apr_status_t) apr_pool_userdata_get(<span class="keywordtype">void</span> **data, const <span class="keywordtype">char</span> *key,
00472                                                 apr_pool_t *pool);
00473 
00474 
00475 <span class="comment">/*</span>
00476 <span class="comment"> * Cleanup</span>
00477 <span class="comment"> *</span>
00478 <span class="comment"> * Cleanups are performed in the reverse order they were registered.  That is:</span>
00479 <span class="comment"> * Last In, First Out.  A cleanup function can safely allocate memory from</span>
00480 <span class="comment"> * the pool that is being cleaned up. It can also safely register additional</span>
00481 <span class="comment"> * cleanups which will be run LIFO, directly after the current cleanup</span>
00482 <span class="comment"> * terminates.  Cleanups have to take caution in calling functions that</span>
00483 <span class="comment"> * create subpools. Subpools, created during cleanup will NOT automatically</span>
00484 <span class="comment"> * be cleaned up.  In other words, cleanups are to clean up after themselves.</span>
00485 <span class="comment"> */</span>
00486 <span class="comment"></span>
00487 <span class="comment">/**</span>
00488 <span class="comment"> * Register a function to be called when a pool is cleared or destroyed</span>
00489 <span class="comment"> * @param p The pool register the cleanup with</span>
00490 <span class="comment"> * @param data The data to pass to the cleanup function.</span>
00491 <span class="comment"> * @param plain_cleanup The function to call when the pool is cleared</span>