apr-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From gst...@apache.org
Subject cvs commit: apr/docs pool-design.html
Date Wed, 25 Jun 2003 21:50:55 GMT
gstein      2003/06/25 14:50:53

  Added:       docs     pool-design.html
  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">
      <title>Using APR Pools</title>
      <div align="right">
        Last modified at [$Date: 2003/06/25 21:50:16 $]
      <h1>Using APR Pools</h1>
        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."
        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:
          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.
            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
            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) {
    do_operation(..., 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 '<tt>continue</tt>' to occur within the loop,
            yet still ensure the pool will be cleared.
          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.
      <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 -->

View raw message