cvs commit: apache-1.3/htdocs/manual/misc API.html
coar98/04/21 05:31:51
Modified:htdocs/manual/misc API.html
Log:
Add Dean's description of what pools there are to the soi-disant
documentation.
Submitted by: Dean Gaudet
Revision ChangesPath
1.15 +171 -33 apache-1.3/htdocs/manual/misc/API.html
Index: API.html
===
RCS file: /export/home/cvs/apache-1.3/htdocs/manual/misc/API.html,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- API.html 1998/04/15 08:50:37 1.14
+++ API.html 1998/04/21 12:31:50 1.15
@@ -494,27 +494,30 @@
response was actually sent).
Resource allocation and resource pools
-
+
One of the problems of writing and designing a server-pool server is
that of preventing leakage, that is, allocating resources (memory,
open files, etc.), without subsequently releasing them. The resource
pool machinery is designed to make it easy to prevent this from
happening, by allowing resource to be allocated in such a way that
they are automatically released when the server is done with
-them.
-
+them.
+
+
The way this works is as follows: the memory which is allocated, file
opened, etc., to deal with a particular request are tied to a
resource pool which is allocated for the request. The pool
-is a data structure which itself tracks the resources in question.
-
+is a data structure which itself tracks the resources in question.
+
+
When the request has been processed, the pool is cleared. At
that point, all the memory associated with it is released for reuse,
all files associated with it are closed, and any other clean-up
functions which are associated with the pool are run. When this is
over, we can be confident that all the resource tied to the pool have
-been released, and that none of them have leaked.
-
+been released, and that none of them have leaked.
+
+
Server restarts, and allocation of memory and resources for per-server
configuration, are handled in a similar way. There is a
configuration pool, which keeps track of resources which were
@@ -524,8 +527,9 @@
opened, and so forth). When the server restarts, and has to reread
the configuration files, the configuration pool is cleared, and so the
memory and file descriptors which were taken up by reading them the
-last time are made available for reuse.
-
+last time are made available for reuse.
+
+
It should be noted that use of the pool machinery isn't generally
obligatory, except for situations like logging handlers, where you
really need to register cleanups to make sure that the log file gets
@@ -538,14 +542,15 @@
resources allocated to a pool never leak (even if you allocate a
scratch string, and just forget about it); also, for memory
allocation, ap_palloc is generally faster than
-malloc.
-
+malloc.
+
+
We begin here by describing how memory is allocated to pools, and then
discuss how other resources are tracked by the resource pool
machinery.
-
+
Allocation of memory in pools
-
+
Memory is allocated to pools by calling the function
ap_palloc, which takes two arguments, one being a pointer to
a resource pool structure, and the other being the amount of memory to
@@ -554,7 +559,7 @@
by looking at the pool slot of the relevant
request_rec; hence the repeated appearance of the
following idiom in module code:
-
+
int my_handler(request_rec *r)
{
@@ -564,14 +569,15 @@
foo = (foo *)ap_palloc (r->pool, sizeof(my_structure));
}
-
+
Note that there is no ap_pfree ---
ap_palloced memory is freed only when the associated
resource pool is cleared. This means that ap_palloc does not
have to do as much accounting as malloc(); all it does in
the typical case is to round up the size, bump a pointer, and do a
-range check.
-
+range check.
+
+
(It also raises the possibility that heavy use of ap_palloc
could cause a server process to grow excessively large. There are
two ways to deal with this, which are dealt with below; briefly, you
@@ -582,9 +588,9 @@
sub-pools below, and is used in the directory-indexing code, in order
to avoid excessive storage allocation when listing directories with
thousands of files).
-
+
Allocating initialized memory
-
+
There are functions which allocate initialized memory, and are
frequently useful. The function ap_pcalloc has the same
interface as ap_palloc, but clears out the memory it
@@ -596,34 +602,157 @@
at least two char * arguments, the last of which must be
NULL. It allocates enough memory to fit copies of each
of the strings, as a unit; for instance:
-
+
ap_pstrcat (r->pool, "foo", "/", "bar", NULL);
-
+
returns a pointer to 8 bytes worth of memory, initialized to
"fo
cvs commit: apache-1.3/htdocs/manual/misc API.html
martin 98/04/15 01:50:37
Modified:htdocs/manual/misc API.html
Log:
Oops: csubst missed a couple of old names.
Revision ChangesPath
1.14 +45 -45apache-1.3/htdocs/manual/misc/API.html
Index: API.html
===
RCS file: /home/cvs/apache-1.3/htdocs/manual/misc/API.html,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -u -r1.13 -r1.14
--- API.html 1998/04/15 08:31:24 1.13
+++ API.html 1998/04/15 08:50:37 1.14
@@ -240,10 +240,10 @@
response (which modules can add to at will), and environment variables
for any subprocesses which are spawned off in the course of servicing
the request. These tables are manipulated using the
-table_get and table_set routines.
+ap_table_get and ap_table_set routines.
Note that the Content-type header value cannot be
- set by module content-handlers using the table_*()
+ set by module content-handlers using the ap_table_*()
routines. Rather, it is set by pointing the content_type
field in the request_rec structure to an appropriate
string. E.g.,
@@ -397,7 +397,7 @@
response handlers have to actually send a request back to the client.
They should begin by sending an HTTP response header, using the
-function send_http_header. (You don't have to do
+function ap_send_http_header. (You don't have to do
anything special to skip sending the header for HTTP/0.9 requests; the
function figures out on its own that it shouldn't do anything). If
the request is marked header_only, that's all they should
@@ -414,11 +414,11 @@
of code, which is the handler which handles GET requests
which have no more specific handler; it also shows how conditional
GETs can be handled, if it's desirable to do so in a
-particular response handler --- set_last_modified checks
+particular response handler --- ap_set_last_modified checks
against the If-modified-since value supplied by the
client, if any, and returns an appropriate code (which will, if
nonzero, be USE_LOCAL_COPY). No similar considerations apply for
-set_content_length, but it returns an error code for
+ap_set_content_length, but it returns an error code for
symmetry.
@@ -430,8 +430,8 @@
if (r->method_number != M_GET) return DECLINED;
if (r->finfo.st_mode == 0) return NOT_FOUND;
-if ((errstatus = set_content_length (r, r->finfo.st_size))
-|| (errstatus = set_last_modified (r, r->finfo.st_mtime)))
+if ((errstatus = ap_set_content_length (r, r->finfo.st_size))
+ || (errstatus = ap_set_last_modified (r, r->finfo.st_mtime)))
return errstatus;
f = fopen (r->filename, "r");
@@ -443,10 +443,10 @@
}
register_timeout ("send", r);
-send_http_header (r);
+ap_send_http_header (r);
if (!r->header_only) send_fd (f, r);
-pfclose (r->pool, f);
+ap_pfclose (r->pool, f);
return OK;
}
@@ -456,11 +456,11 @@
has not yet produced any output can simply return an error code, in
which case the server will automatically produce an error response.
Secondly, it can punt to some other handler by invoking
-internal_redirect, which is how the internal redirection
+ap_internal_redirect, which is how the internal redirection
machinery discussed above is invoked. A response handler which has
internally redirected should always return OK.
-(Invoking internal_redirect from handlers which are
+(Invoking ap_internal_redirect from handlers which are
not response handlers will lead to serious confusion).
Special considerations for authentication
handlers
@@ -471,12 +471,12 @@
Authentication-phase handlers not invoked unless auth is
configured for the directory.
Common auth configuration stored in the core per-dir
- configuration; it has accessors auth_type,
- auth_name, and requires.
+ configuration; it has accessors ap_auth_type,
+ ap_auth_name, and ap_requires.
Common routines, to handle the protocol end of things, at least
- for HTTP basic authentication (get_basic_auth_pw,
+ for HTTP basic authentication (ap_get_basic_auth_pw,
which sets the connection->user structure field
- automatically, and note_basic_auth_failure, which
+ automatically, and ap_note_basic_auth_failure, which
arranges for the proper WWW-Authenticate: header
to be sent back).
@@ -537,7 +537,7 @@
documented here). However, there are two benefits to using it:
resources allocated to a pool never leak (even if you allocate a
scratch string, and just forget about it); also, for memory
-allocation, palloc is generally faster than
+allocation, ap_palloc is generally faster than
malloc.
We begin here by describing how memory is allocated to pools, and then
