<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html><head> <title>Using APR Pools</title> </head> <body> <div align="right"> Last modified at [$Date: 2004-11-24 22:51:51 +0000 (Wed, 24 Nov 2004) $] </div> <h1>Using APR Pools</h1> <p> From <a href="http://subversion.tigris.org/">Subversion</a>, we have learned a <em>lot</em> about how to use pools in a heavily structured/object-based environment. <a href="http://httpd.apache.org/">Apache httpd</a> is a completely different beast: "allocate a request pool. use it. destroy it." </p> <p> 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: </p> <ul> <li> Objects should not have their own pools. An object is allocated into a pool defined by the constructor's caller. The <strong>caller</strong> knows the lifetime of the object and will manage it via the pool. Generally, this also means that objects will not have a "close" or a "free" since those operations will happen implicitly as part of the destruction of the pool the objects live within. </li> <li> <p> Functions should not create/destroy pools for their operation; they should use a pool provided by the caller. Again, the <strong>caller</strong> 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. </p> <p> 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. </p> </li> <li> <p> Whenever an unbounded iteration occurs, a subpool should be used. The general pattern is: </p> <blockquote> <pre> subpool = apr_create_subpool(pool); for (i = 0; i < n; ++i) { apr_pool_clear(subpool); do_operation(..., subpool); } apr_pool_destroy(subpool);</pre> </blockquote> <p> 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 '<tt>continue</tt>' to occur within the loop, yet still ensure the pool will be cleared. </p> </li> <li> Given all of the above, it is pretty well mandatory to pass a pool to <em>every</em> function. Since objects are not recording pools for themselves, and the caller is always supposed to be managing memory, then each function needs a pool, rather than relying on some hidden magic pool. In limited cases, objects may record the pool used for their construction so that they can construct sub-parts, but these cases should be examined carefully. Internal pools can lead to unbounded pool usage if the object is not careful. </li> </ul> <hr> <address>Greg Stein</address> <!-- Created: Wed Jun 25 14:39:57 PDT 2003 --> <!-- hhmts start --> Last modified: Wed Jun 25 14:50:19 PDT 2003 <!-- hhmts end --> </body></html>