|void||apr_pool_join (apr_pool_t *p, apr_pool_t *sub)|
|apr_pool_t *||apr_pool_find (const void *mem)|
|apr_size_t||apr_pool_num_bytes (apr_pool_t *p, int recurse)|
|void||apr_pool_lock (apr_pool_t *pool, int flag)|
For example, if B is a sub pool of A, and you build a table T in pool B, then it's safe to insert data allocated in A or B into T (because B lives at most as long as A does, and T is destroyed when B is cleared/destroyed). On the other hand, if S is a table in pool A, it is safe to insert data allocated in A into S, but it is *not safe* to insert data allocated from B into S... because B can be cleared/destroyed before A is (which would leave dangling pointers in T's data structures).
In general we say that it is safe to insert data into a table T if the data is allocated in any ancestor of T's pool. This is the basis on which the APR_POOL_DEBUG code works -- it tests these ancestor relationships for all data inserted into tables. APR_POOL_DEBUG also provides tools (apr_pool_find, and apr_pool_is_ancestor) for other folks to implement similar restrictions for their own data structures.
However, sometimes this ancestor requirement is inconvenient -- sometimes we're forced to create a sub pool (such as through apr_sub_req_lookup_uri), and the sub pool is guaranteed to have the same lifetime as the parent pool. This is a guarantee implemented by the *caller*, not by the pool code. That is, the caller guarantees they won't destroy the sub pool individually prior to destroying the parent pool.
In this case the caller must call apr_pool_join() to indicate this guarantee to the APR_POOL_DEBUG code. There are a few examples spread through the standard modules.
These functions are only implemented when APR_POOL_DEBUG is set.
|apr_pool_t* apr_pool_find||(||const void *||mem||)|
Find a pool from something allocated in it.
|mem||The thing allocated in the pool|
Guarantee that a subpool has the same lifetime as the parent.
|p||The parent pool|
|void apr_pool_lock||(||apr_pool_t *||pool,|
Lock a pool
|pool||The pool to lock|
|apr_size_t apr_pool_num_bytes||(||apr_pool_t *||p,|
Report the number of bytes currently in the pool
|p||The pool to inspect|
|recurse||Recurse/include the subpools' sizes|