From Subversion, we have learned a lot about how to use pools in a heavily structured/object-based environment. Apache httpd is a completely different beast: "allocate a request pool. use it. destroy it."
In a complex app, that request-style of behavior is not present. Luckily, the "proper" use of pools can be described in just a few rules:
Functions should not create/destroy pools for their operation; they should use a pool provided by the caller. Again, the caller knows more about how the function will be used, how often, how many times, etc. Thus, it should be in charge of the function's memory usage.
As an example, the caller might know that the app will exit upon the function's return. Thus, the function would be creating extra work if it built and destroyed a pool. Instead, it should use the passed-in pool, which the caller is going to be tossing as part of app-exit anyways.
Whenever an unbounded iteration occurs, a subpool should be used. The general pattern is:
subpool = apr_create_subpool(pool);
for (i = 0; i < n; ++i) {
apr_pool_clear(subpool);
do_operation(..., subpool);
}
apr_pool_destroy(subpool);
This pattern prevents the 'pool' from growing unbounded and consuming all of memory. Note that it is slightly more optimal to clear the pool on loop-entry. This pattern also allows for a 'continue' to occur within the loop, yet still ensure the pool will be cleared.