svn commit: rev 42 - commons/serf/trunk/docs

[gs...@apache.org]

Author: gstein
Date: Wed Jun 25 13:40:22 2003
New Revision: 42

Modified:
   commons/serf/trunk/docs/pool-design.txt
Log:
tweak the pool design docs a bit


Modified: commons/serf/trunk/docs/pool-design.txt
==============================================================================
--- commons/serf/trunk/docs/pool-design.txt	(original)
+++ commons/serf/trunk/docs/pool-design.txt	Wed Jun 25 13:40:22 2003
@@ -1,4 +1,4 @@
-Last modified at [$Date: 2003/01/05 00:41:21 $]                 -*-text-*-
+Last modified at [$Date: 2003/06/25 20:40:22 $]                 -*-text-*-
 
 POOL DESIGN
 
@@ -11,7 +11,10 @@
 
 * objects should not have their own pools. an object is allocated into
   a pool defined by the constructor's caller. the *CALLER* knows the
-  lifetime of the object and will manage it via the pool.
+  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 *CALLER* knows
@@ -29,14 +32,17 @@
   
   subpool = apr_create_subpool(pool);
   for (i = 0; i < n; ++i) {
-    do_operation(..., subpool);
-    
     apr_pool_clear(subpool);
+
+    do_operation(..., subpool);
   }
   apr_pool_destroy(subpool);
   
   This pattern prevents the 'pool' from growing unbounded and
-  consuming all of memory.
+  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.
 
 * given all of the above, it is pretty well mandatory to pass a pool
   to *every* function. since objects are not recording pools for