1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html><head> 3 <title>Using APR Pools</title> 4 </head> 5 <body> 6 <h1>Using APR Pools</h1> 7 8 <p> 9 From <a href="http://subversion.tigris.org/">Subversion</a>, we 10 have learned a <em>lot</em> about how to use pools in a heavily 11 structured/object-based environment. 12 <a href="http://httpd.apache.org/">Apache httpd</a> is a 13 completely different beast: "allocate a request pool. use 14 it. destroy it." 15 </p> 16 17 <p> 18 In a complex app, that request-style of behavior is not 19 present. Luckily, the "proper" use of pools can be described in 20 just a few rules: 21 </p> 22 23 <ul> 24 <li> 25 Objects should not have their own pools. An object is 26 allocated into a pool defined by the constructor's caller. The 27 <strong>caller</strong> knows the lifetime of the object and 28 will manage it via the pool. Generally, this also means that 29 objects will not have a "close" or a "free" since those 30 operations will happen implicitly as part of the destruction 31 of the pool the objects live within. 32 </li> 33 34 <li> 35 <p> 36 Functions should not create/destroy pools for their 37 operation; they should use a pool provided by the 38 caller. Again, the <strong>caller</strong> knows more about 39 how the function will be used, how often, how many times, 40 etc. Thus, it should be in charge of the function's memory 41 usage. 42 </p> 43 <p> 44 As an example, the caller might know that the app will exit 45 upon the function's return. Thus, the function would be 46 creating extra work if it built and destroyed a 47 pool. Instead, it should use the passed-in pool, which the 48 caller is going to be tossing as part of app-exit anyways. 49 </p> 50 </li> 51 52 <li> 53 <p> 54 Whenever an unbounded iteration occurs, a subpool should be 55 used. The general pattern is: 56 </p> 57 <blockquote> 58 <pre> 59subpool = apr_create_subpool(pool); 60for (i = 0; i < n; ++i) { 61 apr_pool_clear(subpool); 62 63 do_operation(..., subpool); 64} 65apr_pool_destroy(subpool);</pre> 66 </blockquote> 67 <p> 68 This pattern prevents the 'pool' from growing unbounded and 69 consuming all of memory. Note that it is slightly more 70 optimal to clear the pool on loop-entry. This pattern also 71 allows for a '<tt>continue</tt>' to occur within the loop, 72 yet still ensure the pool will be cleared. 73 </p> 74 </li> 75 76 <li> 77 Given all of the above, it is pretty well mandatory to pass a 78 pool to <em>every</em> function. Since objects are not 79 recording pools for themselves, and the caller is always 80 supposed to be managing memory, then each function needs a 81 pool, rather than relying on some hidden magic pool. In 82 limited cases, objects may record the pool used for their 83 construction so that they can construct sub-parts, but these 84 cases should be examined carefully. Internal pools can lead to 85 unbounded pool usage if the object is not careful. 86 </li> 87 </ul> 88 89 <hr> 90 <address>Greg Stein</address> 91 <!-- Created: Wed Jun 25 14:39:57 PDT 2003 --> 92 <!-- hhmts start --> 93Last modified: Wed Jun 25 14:50:19 PDT 2003 94<!-- hhmts end --> 95 96</body></html> 97