apr__pools_8h-source.html

apr函数库使用手册

00492 <span class="comment"> *                      or destroyed</span>
00493 <span class="comment"> * @param child_cleanup The function to call when a child process is about</span>
00494 <span class="comment"> *                      to exec - this function is called in the child, obviously!</span>
00495 <span class="comment"> */</span>
00496 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_cleanup_register(
00497     apr_pool_t *p,
00498     const <span class="keywordtype">void</span> *data,
00499     apr_status_t (*plain_cleanup)(<span class="keywordtype">void</span> *),
00500     apr_status_t (*child_cleanup)(<span class="keywordtype">void</span> *));
00501 <span class="comment"></span>
00502 <span class="comment">/**</span>
00503 <span class="comment"> * Remove a previously registered cleanup function</span>
00504 <span class="comment"> * @param p The pool remove the cleanup from</span>
00505 <span class="comment"> * @param data The data to remove from cleanup</span>
00506 <span class="comment"> * @param cleanup The function to remove from cleanup</span>
00507 <span class="comment"> * @remarks For some strange reason only the plain_cleanup is handled by this</span>
00508 <span class="comment"> *          function</span>
00509 <span class="comment"> */</span>
00510 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_cleanup_kill(apr_pool_t *p, const <span class="keywordtype">void</span> *data,
00511                                         apr_status_t (*cleanup)(<span class="keywordtype">void</span> *));
00512 <span class="comment"></span>
00513 <span class="comment">/**</span>
00514 <span class="comment"> * Replace the child cleanup of a previously registered cleanup</span>
00515 <span class="comment"> * @param p The pool of the registered cleanup</span>
00516 <span class="comment"> * @param data The data of the registered cleanup</span>
00517 <span class="comment"> * @param plain_cleanup The plain cleanup function of the registered cleanup</span>
00518 <span class="comment"> * @param child_cleanup The function to register as the child cleanup</span>
00519 <span class="comment"> */</span>
00520 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_child_cleanup_set(
00521     apr_pool_t *p,
00522     const <span class="keywordtype">void</span> *data,
00523     apr_status_t (*plain_cleanup)(<span class="keywordtype">void</span> *),
00524     apr_status_t (*child_cleanup)(<span class="keywordtype">void</span> *));
00525 <span class="comment"></span>
00526 <span class="comment">/**</span>
00527 <span class="comment"> * Run the specified cleanup function immediately and unregister it. Use</span>
00528 <span class="comment"> * @a data instead of the data that was registered with the cleanup.</span>
00529 <span class="comment"> * @param p The pool remove the cleanup from</span>
00530 <span class="comment"> * @param data The data to remove from cleanup</span>
00531 <span class="comment"> * @param cleanup The function to remove from cleanup</span>
00532 <span class="comment"> */</span>
00533 APR_DECLARE(apr_status_t) apr_pool_cleanup_run(
00534     apr_pool_t *p,
00535     <span class="keywordtype">void</span> *data,
00536     apr_status_t (*cleanup)(<span class="keywordtype">void</span> *));
00537 <span class="comment"></span>
00538 <span class="comment">/**</span>
00539 <span class="comment"> * An empty cleanup function</span>
00540 <span class="comment"> * @param data The data to cleanup</span>
00541 <span class="comment"> */</span>
00542 APR_DECLARE_NONSTD(apr_status_t) apr_pool_cleanup_null(<span class="keywordtype">void</span> *data);
00543 
00544 <span class="comment">/* Preparing for exec() --- close files, etc., but *don't* flush I/O</span>
00545 <span class="comment"> * buffers, *don't* wait for subprocesses, and *don't* free any memory.</span>
00546 <span class="comment"> */</span><span class="comment"></span>
00547 <span class="comment">/**</span>
00548 <span class="comment"> * Run all of the child_cleanups, so that any unnecessary files are</span>
00549 <span class="comment"> * closed because we are about to exec a new program</span>
00550 <span class="comment"> */</span>
00551 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_cleanup_for_exec(<span class="keywordtype">void</span>);
00552 
00553 <span class="comment"></span>
00554 <span class="comment">/**</span>
00555 <span class="comment"> * @defgroup PoolDebug Pool Debugging functions.</span>
00556 <span class="comment"> *</span>
00557 <span class="comment"> * pools have nested lifetimes -- sub_pools are destroyed when the</span>
00558 <span class="comment"> * parent pool is cleared.  We allow certain liberties with operations</span>
00559 <span class="comment"> * on things such as tables (and on other structures in a more general</span>
00560 <span class="comment"> * sense) where we allow the caller to insert values into a table which</span>
00561 <span class="comment"> * were not allocated from the table's pool.  The table's data will</span>
00562 <span class="comment"> * remain valid as long as all the pools from which its values are</span>
00563 <span class="comment"> * allocated remain valid.</span>
00564 <span class="comment"> *</span>
00565 <span class="comment"> * For example, if B is a sub pool of A, and you build a table T in</span>
00566 <span class="comment"> * pool B, then it's safe to insert data allocated in A or B into T</span>
00567 <span class="comment"> * (because B lives at most as long as A does, and T is destroyed when</span>
00568 <span class="comment"> * B is cleared/destroyed).  On the other hand, if S is a table in</span>
00569 <span class="comment"> * pool A, it is safe to insert data allocated in A into S, but it</span>
00570 <span class="comment"> * is *not safe* to insert data allocated from B into S... because</span>
00571 <span class="comment"> * B can be cleared/destroyed before A is (which would leave dangling</span>
00572 <span class="comment"> * pointers in T's data structures).</span>
00573 <span class="comment"> *</span>
00574 <span class="comment"> * In general we say that it is safe to insert data into a table T</span>
00575 <span class="comment"> * if the data is allocated in any ancestor of T's pool.  This is the</span>
00576 <span class="comment"> * basis on which the APR_POOL_DEBUG code works -- it tests these ancestor</span>
00577 <span class="comment"> * relationships for all data inserted into tables.  APR_POOL_DEBUG also</span>
00578 <span class="comment"> * provides tools (apr_pool_find, and apr_pool_is_ancestor) for other</span>
00579 <span class="comment"> * folks to implement similar restrictions for their own data</span>
00580 <span class="comment"> * structures.</span>
00581 <span class="comment"> *</span>
00582 <span class="comment"> * However, sometimes this ancestor requirement is inconvenient --</span>
00583 <span class="comment"> * sometimes we're forced to create a sub pool (such as through</span>
00584 <span class="comment"> * apr_sub_req_lookup_uri), and the sub pool is guaranteed to have</span>
00585 <span class="comment"> * the same lifetime as the parent pool.  This is a guarantee implemented</span>
00586 <span class="comment"> * by the *caller*, not by the pool code.  That is, the caller guarantees</span>
00587 <span class="comment"> * they won't destroy the sub pool individually prior to destroying the</span>
00588 <span class="comment"> * parent pool.</span>
00589 <span class="comment"> *</span>
00590 <span class="comment"> * In this case the caller must call apr_pool_join() to indicate this</span>
00591 <span class="comment"> * guarantee to the APR_POOL_DEBUG code.  There are a few examples spread</span>
00592 <span class="comment"> * through the standard modules.</span>
00593 <span class="comment"> *</span>
00594 <span class="comment"> * These functions are only implemented when #APR_POOL_DEBUG is set.</span>
00595 <span class="comment"> *</span>
00596 <span class="comment"> * @{</span>
00597 <span class="comment"> */</span>
00598 #if APR_POOL_DEBUG || defined(DOXYGEN)<span class="comment"></span>
00599 <span class="comment">/**</span>
00600 <span class="comment"> * Guarantee that a subpool has the same lifetime as the parent.</span>
00601 <span class="comment"> * @param p The parent pool</span>
00602 <span class="comment"> * @param sub The subpool</span>
00603 <span class="comment"> */</span>
00604 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_join(apr_pool_t *p, apr_pool_t *sub);
00605 <span class="comment"></span>
00606 <span class="comment">/**</span>
00607 <span class="comment"> * Find a pool from something allocated in it.</span>
00608 <span class="comment"> * @param mem The thing allocated in the pool</span>
00609 <span class="comment"> * @return The pool it is allocated in</span>
00610 <span class="comment"> */</span>
00611 APR_DECLARE(apr_pool_t *) apr_pool_find(const <span class="keywordtype">void</span> *mem);
00612 <span class="comment"></span>
00613 <span class="comment">/**</span>
00614 <span class="comment"> * Report the number of bytes currently in the pool</span>
00615 <span class="comment"> * @param p The pool to inspect</span>
00616 <span class="comment"> * @param recurse Recurse/include the subpools' sizes</span>
00617 <span class="comment"> * @return The number of bytes</span>
00618 <span class="comment"> */</span>
00619 APR_DECLARE(apr_size_t) apr_pool_num_bytes(apr_pool_t *p, <span class="keywordtype">int</span> recurse);
00620 <span class="comment"></span>
00621 <span class="comment">/**</span>
00622 <span class="comment"> * Lock a pool</span>
00623 <span class="comment"> * @param pool The pool to lock</span>
00624 <span class="comment"> * @param flag  The flag</span>
00625 <span class="comment"> */</span>
00626 APR_DECLARE(<span class="keywordtype">void</span>) apr_pool_lock(apr_pool_t *pool, <span class="keywordtype">int</span> flag);
00627 
00628 <span class="comment">/* @} */</span>
00629 
00630 #else <span class="comment">/* APR_POOL_DEBUG or DOXYGEN */</span>
00631 
00632 #ifdef apr_pool_join
00633 #undef apr_pool_join
00634 #endif
00635 #define apr_pool_join(a,b)
00636 
00637 #ifdef apr_pool_lock
00638 #undef apr_pool_lock
00639 #endif
00640 #define apr_pool_lock(pool, lock)
00641 
00642 #endif <span class="comment">/* APR_POOL_DEBUG or DOXYGEN */</span>
00643 <span class="comment"></span>
00644 <span class="comment">/** @} */</span>
00645 
00646 #ifdef __cplusplus
00647 }
00648 #endif
00649 
00650 #endif <span class="comment">/* !APR_POOLS_H */</span>
</div></pre><hr size="1"><address style="align: right;"><small>Generated on Mon Feb 7 13:18:25 2005 for Apache Portable Runtime by
<a href="../../../www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border=0 ></a> 1.3.7 </small></address>
</body>
</html>