kbe/src/lib/dependencies/apr/docs/pool-design.html
Last modified at [$Date: 2004-11-24 17:51:51 -0500 (Wed, 24 Nov 2004) $]
From Subversion, we have learned a lot about how to use pools in a heavily structured/object-based environment. Apache httpd 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 caller 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 caller 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.
Whenever an unbounded iteration occurs, a subpool should be used. The general pattern is:
Given all of the above, it is pretty well mandatory to pass a pool to every 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.
Greg SteinLast modified: Wed Jun 25 14:50:19 PDT 2003