[prev in list] [next in list] [prev in thread] [next in thread] 

List:       apr-cvs
Subject:    cvs commit: apr/docs pool-design.html
From:       gstein () apache ! org
Date:       2003-06-25 21:50:55
[Download RAW message or body]

gstein      2003/06/25 14:50:53

  Added:       docs     pool-design.html
  Log:
  move serf's pool-design.txt here as part of the actual APR docs.
  
  Revision  Changes    Path
  1.1                  apr/docs/pool-design.html
  
  Index: pool-design.html
  ===================================================================
  <!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: 2003/06/25 21:50:16 $]
      </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>
  
  
  
[prev in list] [next in list] [prev in thread] [next in thread]

Configure | About | News | Add a list | Sponsored by KoreLogic