Apache 1.3 API Documentation

Routine ap_make_sub_pool

Definition:

pool *ap_make_sub_pool(pool *p);
     

Usage example:

No examples available.
     

This function creates a new pool area 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 ap_destroy_pool), any sub-pools it may have are also destroyed recursively.

An example of when this hierarchy concept is useful can be found in the mod_autoindex, which is used to generate automatic directory listings. Since mod_autoindex 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 per-filename processing in it, and clears it for each new file.

If the pointer passed to ap_make_sub_pool is NULL, a new top-level (i.e., 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 per-request processing, and hence should be sub-pools of the request's pool (r->pool) to ensure that they are properly cleaned up on request completion.

See also:

ap_bytes_in_pool, ap_clear_pool, ap_destroy_pool, ap_find_pool, ap_palloc, ap_pcalloc, ap_pclosedir, ap_pclosef, ap_pclosesocket, ap_pduphostent, ap_pfclose, ap_pfdopen, ap_pfopen, ap_pgethostbyname, ap_pool, ap_pool_is_ancestor, ap_pool_join, ap_popendir, ap_popenf, ap_pregcomp, ap_pregfree, ap_psocket, ap_pstrcat, ap_pstrdup, ap_pstrndup, pool

Previous: ap_make_full_path Next: ap_make_table

Table of Contents (Routines, Structures, Data Cells, Constants)