coar 98/04/10 05:17:41
Modified: . API-dict.html
Log:
Toying with an alternate format, and adding a little real
documentation at the same time.
Revision Changes Path
1.5 +40 -7 apache-devsite/API-dict.html
Index: API-dict.html
===================================================================
RCS file: /export/home/cvs/apache-devsite/API-dict.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- API-dict.html 1998/04/09 01:01:06 1.4
+++ API-dict.html 1998/04/10 12:17:40 1.5
@@ -1377,15 +1377,48 @@
definition/description
</P>
</DD>
+ </DL>
<HR>
- <DT><A NAME="make_sub_pool"><SAMP>make_sub_pool</SAMP></A>
- </DT>
- <DD>
- <P>
- definition/description
- </P>
- </DD>
+ <H3><A NAME="make_sub_pool"><SAMP>make_sub_pool</SAMP></A></H3>
+ <DL>
+ <DT><CODE><A HREF="#pool">pool</A>
+ *make_sub_pool(<A HREF="#pool">pool</A> *p)</CODE>
+ </DT>
+ <DD>
+ <P>
+ This function creates a new <A HREF="#pool">pool area</A>
+ for memory allocation. The
+ new area is considered to be a "child" of the pool
+ passed to the routine; this permits a hierarchy of related storage
+ areas. When a pool is destroyed (see
+ <A HREF="#destroy_pool"><SAMP>destroy_pool</SAMP></A>),
+ any sub-pools it may have are also destroyed recursively.
+ </P>
+ <P>
+ An example of when this hierarchy concept is useful can be found in the
+ <A HREF="http://www.apache.org/docs/mod/mod_autoindex.html";
+ >automatic directory listing module</A>. Since the module can't
+ tell in advance how many files it will have to list, nor how long the
+ names will be, nor what other functions might need to allocate memory
+ to process the request, it creates a sub-pool of the one associated
+ with the request, does the <em>per</EM>-filename processing in
+ it, and clears it for each new file.
+ </P>
+ <P>
+ If the pointer passed to <SAMP>make_sub_pool</SAMP> is
<CODE>NULL</CODE>,
+ a new top-level (<EM>i.e.</EM>, parentless) pool is created. This
+ is generally not recommended, however, since the only record of a
+ pool's existence is the pointer returned - a simple logic error can
+ result in pools being created and lost, along with any allocations
+ made in them. Most pools are created to deal with <EM>per</EM>-request
+ processing, and hence should be sub-pools of the request's pool
+ (<A HREF="#request_rec"><SAMP>r->pool</SAMP></A>) to ensure that
+ they are properly cleaned up on request completion.
+ </P>
+ </DD>
+ </DL>
<HR>
+ <DL>
<DT><A NAME="make_table"><SAMP>make_table</SAMP></A>
</DT>
<DD>
