Skip to content

Commit

Permalink
Doc updates.
Browse files Browse the repository at this point in the history
  • Loading branch information
jgdavidson committed Dec 8, 2009
1 parent 22c0ef3 commit 0bc5557
Show file tree
Hide file tree
Showing 8 changed files with 723 additions and 35 deletions.
72 changes: 57 additions & 15 deletions doc/Ns_ConnContent.3
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,16 +28,16 @@
'\" version of this file under either the License or the GPL.
'\"
'\"
'\" $Header: /Users/dossy/Desktop/cvs/aolserver/doc/Ns_ConnContent.3,v 1.3 2006/04/19 17:37:30 jgdavidson Exp $
'\" $Header: /Users/dossy/Desktop/cvs/aolserver/doc/Ns_ConnContent.3,v 1.4 2009/12/08 04:13:18 jgdavidson Exp $
'\"
'\"
.so man.macros

.TH Ns_ConnContent 3 4.0 AOLserver "AOLserver Library Procedures"
.TH Ns_ConnContent 3 4.6 AOLserver "AOLserver Library Procedures"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Ns_ConnContent, Ns_ConnContentLength, Ns_ConnContentFd, Ns_ConnContentOnDisk \- Routines to access request content
Ns_ConnContent, Ns_ConnContentLength, Ns_ConnContentAvail, Ns_ConnContentFd, Ns_ConnContentOnDisk \- routines to access request content
.SH SYNOPSIS
.nf
\fB#include "ns.h"\fR
Expand All @@ -49,38 +49,70 @@ int
\fBNs_ConnContentLength\fR(\fINs_Conn *conn\fR)
.sp
int
\fBNs_ConnContentAvail\fR(\fINs_Conn *conn\fR)
.sp
int
\fBNs_ConnContentFd\fR(\fINs_Conn *conn\fR)
.sp
int
\fBNs_ConnContentOnDisk\fR(\fINs_Conn *conn\fR)
.SH ARGUMENTS
.AS Ns_Conn *conn in
.AS Ns_Conn *conn
.AP Ns_Conn *conn in
Pointer to given connection.
.sp
.BE
.SH DESCRIPTION
.PP
These procedures provide access to the request content sent with a
request.
These procedures provide access to the content sent with a
request, e.g., a FORM post or PUT data.

.TP
char *\fBNs_ConnContent\fR
Returns a pointer to the content in memory. The result of
\fBNs_ConnContent\fR is not guarenteed to be null-terminated. Safe
\fBNs_ConnContent\fR is not guaranteed to be null-terminated. Safe
code should be careful to use the result of \fBNs_ConnContentLength\fR
to avoid overrun.
to avoid overrun. Small content is in memory only; larger content
is mapped from an opened temporary file. The result is managed by
the server; the caller should not attempt to free or unmap the result.
.sp
NOTE: Attempting to invoke \fBNs_ConnContent\fR for large content
simultaneously in many active connection threads may lead to the
server running out of virtual memory. For large content (e.g.,
large multipart file uploads), it's best
to access the content incrementally via the open temporary file
available via \fBNs_ConnContentFd\fR.

.TP
int \fBNs_ConnContentFd\fR
Returns a file descriptor to an open temporary file which contains
the content.
the content. Large content begin in a temporary file and smaller
requests are copied to a file when requested. Open file is managed
by the server; the caller should not close it directly.
.sp
NOTE: See the \fBNs_GetTemp\fR routine to details on how the
open file is managed within the server.

.TP
int \fBNs_ConnContentLength\fR
Returns the length of the memory buffer and/or the size of the open
temporary file. Any trailing \r\n sent beyond the content from
common browsers on a POST request is not included.
temporary file which has (or will be) uploaded from the client.
Any trailing \r\n sent beyond the content from
common browsers on a POST request is not included. As noted below,
all content is pre-read before connection processing begins. The
only exception is in a possible NS_FILTER_READ filter which will
fire after any read requests after the HTTP request and header lines
have been received. See \fBNs_ConnContentAvail\fR for more detail.

.TP
int \fBNs_ConnContentAvail\fR
Returns the number of bytes currently uploaded. As noted below, all
content is pre-read before connection processing begins so the result
of this routine will always equal that of \fBNs_ConnContentLength\fR
with the possible exception of being called within an NS_FILTER_READ
filter callback where it may be less (all content not yet received)
or perhaps more before the server truncates any spurious content
received (e.g., any trailing \\r\\n from a form upload).

.TP
int \fBNs_ConnContentOnDisk\fR
Expand All @@ -101,9 +133,19 @@ small requests (the majority of simple POST's) are copied to memory.
.PP
There is no need for a request processing extension to consider
possible delays in reading content from the client as all content
is available before connection processing begins. The rationale
is available before connection processing begins. The only exception
is during an NS_FILTER_READ callback (see \fBNs_RegisterCallback\fR
which will fire within
the thread performing the pre-read, possibly before any content has
been received. The difference between the results of
\fBNs_ConnContentLength\fR and \fBNs_ConnContentAvail\fR may be used
to determine if all content is not yet available during a read
filter; accessing partially uploaded content is not safe.

.PP
The rationale
for this approach is that the driver thread can efficiently multiplex
reading content for serveral request, tolerating any network delays.
reading content for several request, tolerating any network delays.
Legacy direct content reading routines, for example, \fBNs_ConnRead\fR,
are now emulated on top of the \fBNs_ConnContent\fR.

Expand Down Expand Up @@ -132,7 +174,7 @@ original location of the content.
.PP
The design goal of the server is to support the ordinary case of
reasonably small content requests (i.e., POST forms and small file
uploads) in a convienent way without limiting a custom app to support
uploads) in a convenient way without limiting a custom app to support
very large requests. In particular, a call to \fBNs_ConnGetQuery\fR
for a \fImultipart/file-upload\fR POST will result in an implicit
call to \fBNs_ConnContent\fR to parse the fields. This could require
Expand All @@ -149,7 +191,7 @@ a HTTP method other than \fIGET\fR or \fIPOST\fR required by
\fBNs_ConnGetQuery\fR, e.g., \fIPUT\fR.

.SH "SEE ALSO"
Ns_Conn(3), Ns_ConnRead(3), ns_limits(n), ns_conn(n)
Ns_Conn(3), Ns_ConnRead(3), Ns_GetTemp(3), ns_limits(n), ns_conn(n)

.SH KEYWORDS
connection, content
126 changes: 114 additions & 12 deletions doc/Ns_Filter.3
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,35 +28,137 @@
'\" version of this file under either the License or the GPL.
'\"
'\"
'\" $Header: /Users/dossy/Desktop/cvs/aolserver/doc/Ns_Filter.3,v 1.5 2003/04/10 22:00:42 shmooved Exp $
'\" $Header: /Users/dossy/Desktop/cvs/aolserver/doc/Ns_Filter.3,v 1.6 2009/12/08 04:13:18 jgdavidson Exp $
'\"
'\"
.so man.macros

.TH Ns_Filter 3 4.0 AOLserver "AOLserver Library Procedures"
.TH Ns_Filter 3 4.6 AOLserver "AOLserver Library Procedures"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Ns_RegisterCleanup, Ns_RegisterConnCleanup, Ns_RegisterFilter, Ns_RegisterServerTrace \- library procedures
Ns_RegisterFilter \- manage callbacks during a connection
.SH SYNOPSIS
.nf
\fB#include "ns.h"\fR
.sp
\fBNs_RegisterCleanup\fR(\fIarg, arg\fR)
.sp
\fBNs_RegisterConnCleanup\fR(\fIarg, arg\fR)
.sp
\fBNs_RegisterFilter\fR(\fIarg, arg\fR)
.sp
\fBNs_RegisterServerTrace\fR(\fIarg, arg\fR)
void
\fBNs_RegisterFilter\fR(\fIchar *server, char *method, char *url, Ns_FilterProc *proc, int when, void *arg\fR)

.SH ARGUMENTS
.AS Ns_FilterProc *proc
.AP char *server in
Name of virtual server.

.AP char *method in
Glob matching pattern for requested methods.

.AP char *url in
Glob matching pattern for requested urls.

.AP int when in
OR-ed combination of the values \fBNS_FILTER_READ\fR,
\fBNS_FILTER_PRE_QUEUE\fR, \fBNS_FILTER_PRE_AUTH\fR,
\fBNS_FILTER_POST_AUTH\fR, \fBNS_FILTER_WRITE\fR, and
\fBNS_FILTER_TRACE\fI indicating the connection state at
which \fIproc\fR should be invoked.

.AP void *arg in
Arbitrary one-word value to pass to \fIproc\fR.

.AP Ns_FilterProc *proc in
Procedure to invoke when the connection reaches a requested
state.

.BE


.SH DESCRIPTION
.PP
These functions ...
\fBNs_RegisterFilter\fR may be called during server initialization to
register callbacks to execute at various points during the connection
lifetime.

.PP
The \fIwhen\fR argument to \fBNs_RegisterFilter\fR indicates when the
callback is to be invoked. It consists of an OR-ed combinations of
any of the following values:
.TP
NS_FILTER_READ
Invoke \fIproc\fR after each read from the client. If there is no
content to be uploaded (e.g., a simple GET request), this callback
will fire just once after the HTTP request and headers lines have
been read (which is considered the minimum context required for a
valid connection). If content is to be uploaded (e.g., on a PUT
request with a non-zero Content-length: header), the routine will
be invoked after any subsequent reads which may be required to
receive the uploaded content. During this phase, the result of
\fBNs_ConnContentAvail\fR may be less than \fBNs_ConnContentLength\fR,
indicating content has not fully been uploaded.
If \fIproc\fR
returns a value other than \fBNS_OK\fR, the connection will be
aborted.

.sp
NOTE(1): It is not safe to access the connection content during an
\fBNS_FILTER_READ\fR callback with, e.g., a call to \fBNs_ConnContent\fR.
It is only safe to access the connction request and headers and
query the upload progress.

.sp
NOTE(2): This callback will be invoked in a thread other than the
thread used to process the connection. This may either be
the "driver" thread used to accept and multiplex reads for all normal
socket connections or one of the specialized read-ahead threads
used to handle SSL connections. In either case, it will not be
possible to store context in thread-local storage to be later accessed
during connection processing. See the \fBNs_ClsAlloc\fR, \fBNs_ClsSet\fR, and
\fBNs_ClsGet\fR \fIconnection local storage\fR routines for a method to
store arbitary context between threads.

.sp
NOTE(3): Any \fBTcl_Interp\fR allocated with \fBNs_GetConnInterp\fR
will be released before switching threads, clearing any global
variables or other state you may have set. Again, use \fIconnection
local stoarge\fR interface with the \fBns_cls\fR command for this
purpose.

.TP
NS_FILTER_PRE_QUEUE
Invoke \fIproc\fR after all content has been read from the client.
This callback will occur just once within the single "driver" thread
and can be used to register one or more \fBNs_QueueWait\fR callbacks
to access addition, possibly blocking network resources before
queueing the thread for processing.
If this \fIproc\fR returns a value other than \fBNS_OK\fR, the conneciton
will be aborted.

.sp
NOTE: See the comments above for \fBNS_FILTER_READ\fR for caveats
of \fIproc\fR being invoked in a thread other than the conneciton
processing thread.

.TP
NS_FILTER_PRE_AUTH
Invoke \fIproc\fR just before connection authentication.

.TP
NS_FILTER_POST_AUTH
Invoke \fIproc\fR just after a successful authentication.

.TP
NS_FILTER_WRITE
Invoke \fIproc\fR after each write to the client.
If \fIproc\fR
returns a value other than \fBNS_OK\fR, the connection will be
aborted.

.TP
NS_FILTER_TRACE


.SH "SEE ALSO"
nsd(1), info(n)
Ns_RegisterConnCleanup(3), ns_register_filter(n), Ns_RegisterServerTrace(3)

.SH KEYWORDS

92 changes: 92 additions & 0 deletions doc/Ns_RegisterConnCleanup.3
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
'\"
'\" The contents of this file are subject to the AOLserver Public License
'\" Version 1.1 (the "License"); you may not use this file except in
'\" compliance with the License. You may obtain a copy of the License at
'\" http://aolserver.com/.
'\"
'\" Software distributed under the License is distributed on an "AS IS"
'\" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
'\" the License for the specific language governing rights and limitations
'\" under the License.
'\"
'\" The Original Code is AOLserver Code and related documentation
'\" distributed by AOL.
'\"
'\" The Initial Developer of the Original Code is America Online,
'\" Inc. Portions created by AOL are Copyright (C) 1999 America Online,
'\" Inc. All Rights Reserved.
'\"
'\" Alternatively, the contents of this file may be used under the terms
'\" of the GNU General Public License (the "GPL"), in which case the
'\" provisions of GPL are applicable instead of those above. If you wish
'\" to allow use of your version of this file only under the terms of the
'\" GPL and not to allow others to use your version of this file under the
'\" License, indicate your decision by deleting the provisions above and
'\" replace them with the notice and other provisions required by the GPL.
'\" If you do not delete the provisions above, a recipient may use your
'\" version of this file under either the License or the GPL.
'\"
'\"
'\" $Header: /Users/dossy/Desktop/cvs/aolserver/doc/Ns_RegisterConnCleanup.3,v 1.1 2009/12/08 04:13:18 jgdavidson Exp $
'\"
'\"
.so man.macros

.TH Ns_Cleanup 3 4.5 AOLserver "AOLserver Library Procedures"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Ns_RegisterCleanup, Ns_RegisterConnCleanup \- manage connection cleanup callbacks
.SH SYNOPSIS
.nf
\fB#include "ns.h"\fR
.sp
void
\fBNs_RegisterCleanup\fR(\fINs_TraceProc *proc, void *arg\fR)
.sp
void
\fBNs_RegisterConnCleanup\fR(\fIchar *server, Ns_TraceProc *proc, void *arg\fR)

.SH ARGUMENTS
.AS Ns_TraceProc *proc
.AP char *server in
Name of virtual server.

.AP void *arg in
Arbitrary one-word value to pass to \fIproc\fR.

.AP Ns_TraceProc *proc in
Procedure to invoke at the end of connection processing.

.BE

.SH DESCRIPTION
.PP
These routines manage callbacks which are invoked in LIFO order at the
end of a conneciton.

.PP
At the end of a connection, regardless of success or error, \fIproc\fR
will be invoked. It should have arguments and result that match
the type \fBNs_TraceProc\fR:
.sp
.CS
typedef void (Ns_TraceProc)(void \fIarg\fR, Ns_Conn *\fIconn\fR);
.CE
.sp
The \fIarg\fR will have the same values as passed to
\fBNs_RegisterConnCleanup\fR when the callback was created. The
\fIconn\fR will be a pointer to the current connection. The
\fIproc\fR may perform any actions necessary to free resources which
may have been allocated and initalized in the course of the connection.

.PP
\fBNs_RegisterCleanup\fR is equivalent to \fBNs_RegisterConnCleanup\fR
with the \fIserver\fR argument set to the currently initializing
server.

.SH "SEE ALSO"
Ns_RegisterFilter(3), Ns_RegisterServerTrace(3)

.SH KEYWORDS
trace, callback, cleanup
Loading

0 comments on commit 0bc5557

Please sign in to comment.