diff --git a/doc/Ns_ConnContent.3 b/doc/Ns_ConnContent.3 index 430d349..8417fa7 100644 --- a/doc/Ns_ConnContent.3 +++ b/doc/Ns_ConnContent.3 @@ -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 @@ -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 @@ -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. @@ -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 @@ -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 diff --git a/doc/Ns_Filter.3 b/doc/Ns_Filter.3 index 25a8397..734a347 100644 --- a/doc/Ns_Filter.3 +++ b/doc/Ns_Filter.3 @@ -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 diff --git a/doc/Ns_RegisterConnCleanup.3 b/doc/Ns_RegisterConnCleanup.3 new file mode 100644 index 0000000..e5d9ae8 --- /dev/null +++ b/doc/Ns_RegisterConnCleanup.3 @@ -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 diff --git a/doc/Ns_RegisterServerTrace.3 b/doc/Ns_RegisterServerTrace.3 new file mode 100644 index 0000000..5a65850 --- /dev/null +++ b/doc/Ns_RegisterServerTrace.3 @@ -0,0 +1,91 @@ + +'\" +'\" 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_RegisterServerTrace.3,v 1.1 2009/12/08 04:13:18 jgdavidson Exp $ +'\" +'\" +.so man.macros + +.TH Ns_RegisterServerTrace 3 4.5 AOLserver "AOLserver Library Procedures" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +Ns_RegisterServerTrace \- invoke cleanup callbacks +.SH SYNOPSIS +.nf +\fB#include "ns.h"\fR +.sp +void +\fBNs_RegisterServerTrace\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 +The \fBNs_RegisterServerTrace\fR routines registers a callbacks to +be invoked in FIFO order at the end of a conneciton. The callback +will only be invoked if the connection executed successfully. + +.PP +At the end of a successful connection, \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. + +.SH NOTE +The \fBNs_RegisterConnCleanup\fR routine, which invokes callbacks +in LIFO order whether the connection is successful or not, may be +more appropriate for reclaiming resources allocated during a +connection. + +.SH "SEE ALSO" +Ns_RegisterConnCleanup(3), Ns_RegisterServerTrace(3) + +.SH KEYWORDS +trace, callback, cleanup diff --git a/doc/Ns_TempFile.3 b/doc/Ns_TempFile.3 index 8256a62..6416c33 100644 --- a/doc/Ns_TempFile.3 +++ b/doc/Ns_TempFile.3 @@ -28,31 +28,70 @@ '\" version of this file under either the License or the GPL. '\" '\" -'\" $Header: /Users/dossy/Desktop/cvs/aolserver/doc/Ns_TempFile.3,v 1.1 2002/09/28 19:58:27 jgdavidson Exp $ +'\" $Header: /Users/dossy/Desktop/cvs/aolserver/doc/Ns_TempFile.3,v 1.2 2009/12/08 04:13:18 jgdavidson Exp $ '\" '\" .so man.macros -.TH Ns_TempFile 3 4.0 AOLserver "AOLserver Library Procedures" +.TH Ns_GetTemp 3 4.5 AOLserver "AOLserver Library Procedures" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -Ns_GetTemp, Ns_ReleaseTemp \- library procedures +Ns_GetTemp, Ns_ReleaseTemp \- routines for efficient open temp files .SH SYNOPSIS .nf \fB#include "ns.h"\fR .sp -\fBNs_GetTemp\fR(\fIarg, arg\fR) +int +\fBNs_GetTemp\fR(\fIvoid\fR) .sp -\fBNs_ReleaseTemp\fR(\fIarg, arg\fR) +void +\fBNs_ReleaseTemp\fR(\int fd\fR) +.AS int fd +.AP int fd in +File descriptor for open temp file returned from a prior call to \fBNs_GetTemp\fR. .BE .SH DESCRIPTION .PP -These functions ... +The \fBNs_GetTemp\fR and \fBNs_Release\fR routines provide a means to efficiently +use open temporary files when necessary to handle data too large for in-memory +structures or to facilitate passing content to forked processes. The +approach is to leave some files open when not in use, avoiding comparably expensive +\fBcreat\fR and \fBclose\fR system calls in favor of quick \fBftruncate\fR's. +The server uses this interface internally to support large-content uploads into +temp files (see \fBNs_ConnContentFd\fR) and to support the open files needed +to send content to and from CGI's. + +.TP +int \fBNs_GetTemp(void)\fR +To use a temporary file, call \fBNs_GetTemp\fR. The result will be a a file +descriptor to an empty file opened in read+write mode located in a +server-configure temporary location. If no more files can be opened, the result +is -1. The open file descriptor can then be used to write content, seek to any +location, and read back bytes. When no longer needed, the file descriptor +can be released by passing it to \fBNs_ReleaseTemp\fR. +.sp +An open file returned by \fBNs_GetTemp\fR may also be used with a higher-level +buffering API, e.g. \fBfdopen\fR to get an open \fIFILE *\fR object. In the case +it is inconvenient or not possible to later disassociate the open file descriptor, +the API's close routine (e.g., \fBfclose\fR) can be called instead of +\fBNs_ReleaseTemp\fR. While the temp file cannot be efficient re-used in this case, +such usage will not lead to any underlying resource leaks or corruption. +.sp +Note that the actual underlying file cannot be accessed by name outside of the +running server. On Unix, the files are deleted just after open for the first +time and on Windows the \fI_SH_DENYRW\fR flag inhibits sharing. This is done +both to ensure cleanup at server shutdown or failure and also provides a security benefit, inhibiting other processes from being able to view the content +temporarily stored in the files. + +.TP +void \fBNs_ReleaseTemp(int fd)\fR +\fBNs_ReleaseTemp\fR returns an open file descriptor to a cache for re-use, +first truncating any data which may be present. .SH "SEE ALSO" -nsd(1), info(n) +Ns_ConnContentFd(3) .SH KEYWORDS - +file \ No newline at end of file diff --git a/doc/ns_cls.n b/doc/ns_cls.n new file mode 100644 index 0000000..2b27992 --- /dev/null +++ b/doc/ns_cls.n @@ -0,0 +1,81 @@ +'\" +'\" 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_cls.n,v 1.1 2009/12/08 04:13:18 jgdavidson Exp $ +'\" +'\" +.so man.macros + +.TH ns_cls n 4.6 AOLserver "AOLserver Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +ns_cls \- connection local storage command +.SH SYNOPSIS +\fBns_cls \fBalloc\fR +.sp +\fBns_cls \fget\fR \fIid\fR +.sp +\fBns_cls \fset\fR \fIid\fR \fIstring\fR +.BE + +.SH DESCRIPTION +.PP +The \fBns_cls\fR command provides Tcl-level access to the \fBNs_Cls\fR +connection-local storage interface. This can be used to managed +data between interpreters and threads where global variables cannot +be utilized. The semantics are similar to the thread-local storage +\fBNs_Tls\fR interface and \fBns_tls\fR commmand. + +.SH USAGE +.PP +With the \fBalloc\fR option, \fBns_cls\fR returns a unique integer +indentifier later used with the \fBget\fR and \fBset\fR options. +It is only safe to call \fBns_cls alloc\fR at server startup. The +resulting \fIid\fR can be passed as an argument to callback +registration routines, e.g., \fBns_register_filter\fR and +\fBns_register_proc\fR. + +.PP +The \fBset\fR and \fBget\fR options use the \fIid\fR returned by +\fBalloc\fR to store and retrieve strings unique to the active +connection, respectively. Space utilized for storage of the string +is automatically reclaimed by the server whenever it is modified +and when the connection is closed. + +.SH EXAMPLE +See the \fBns_quewait\fR man page for an example of using \fBns_cls\fR. + +.SH "SEE ALSO" +Ns_ClsAlloc(3), Ns_ClsGet(3), Ns_ClsSet(3), +Ns_TlsAlloc(3), Ns_TlsGet(3), Ns_TlsSet(3), +ns_quewait(n), ns_register_filter(n), ns_register_proc(n), + +.SH KEYWORDS +callback, connection diff --git a/doc/ns_quewait.n b/doc/ns_quewait.n new file mode 100644 index 0000000..4c214c0 --- /dev/null +++ b/doc/ns_quewait.n @@ -0,0 +1,158 @@ +'\" +'\" 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_quewait.n,v 1.1 2009/12/08 04:13:18 jgdavidson Exp $ +'\" +'\" +.so man.macros + +.TH ns_quewait n 4.6 AOLserver "AOLserver Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +ns_quewait \- pre-queue network I/O callback interface +.SH SYNOPSIS +\fBns_quewait \fIchanId\fR \fBreadable\fR \fItimeout script\fR +.sp +\fBns_quewait \fIchanId\fR \fBwritable\fR \fItimeout script\fR +.BE + +.SH DESCRIPTION +.PP +The \fBns_quewait\fR command enables Tcl-level use of the +\fBNs_QueueWait\fR event callback interface. This interface allows +interacting with one or more, possibly blocking, network resources +before a connection is queued for processing by a connection thread. +The rationale is to perform possibly blocking and/or long-running +network requests using an efficient event-driven programming approach +instead of via blocking I/O calls during connection processing. An +initial call to \fBns_quewait\fR can be performed in a connection +filter registered with the \fBns_register_filter\fR command using +the \fIprequeue\fR option; calling \fBns_quewait\fR +at any other time will result in an error exception. + +.PP +As callbacks occurs within a "driver" accept and read-ahead thread, +the caller needs to be careful not to block reading or writing to +the given channel which would stall the connection accept and +read-ahead functions of the server. + +.SH USAGE +.PP +With the \fBreadable\fR option, the given \fIscript\fR will be +invoked when content can be read from \fIchanId\fR without blocking. +With the \fBwritable\fR option, the script will be invoked when +content can be written to \fIchanId\fR without blocking. In both +cases, the server will only wait up to the absolute time specified +by \fItimeout\fR. The value of \fItimeout\fR can be onstructed +using the \fBns_time\fR command. + +.PP +Note that the server is monitoring the state of the channel's +underlying socket; Tcl's normal buffering facilities may affect +this result (see \fBfconfigure\fR for means to configure the buffering +behavior of the channel). + + +.PP +When the \fIscript\fR is invoked, an additional argument will be appended +to indicate why the callback is occuring. This will normally match +the event for which the callback was registered, i.e., \fBreadable\fR +or \fBwritable\fR but may also be one of the following: + +.TP +\fBtimeout\fR +The channel was not readable or writable in the given absolute \fItimeout\fR +value. In this case, the callback could abort it's attempt to interact +with the remote resource. + +.TP +\fBdropped\fR +The HTTP connection was dropped and will not be processed by +a connection thread. The callback should perform whatever action is +necessary to abort the remote network resource request. + +.SH EXAMPLE +.PP +The server-startup code uses a pre-queue filter which fires after +all request and content data has been received from a client. It +makes an async connection to remote network resource and uses +\fBns_quewait\fR to interact with the remote server. + +.CS + +# Allocate a connection-local-storage (CLS) slot for the search results. +set cls [ns_cls alloc] + +# Register a pre-queue filter to start the search I/O. +ns_register_filter prequeue GET /search dosearch.prequeue $cls + +proc dosearch.prequeue {cls why} { + set s [socket -async 192.168.1.10 8888] + set now [ns_time] + set timeout [ns_time incr $now 1]; # NB: Total time for send+recv. + ns_quewait $s writable $timeout [list dosearch.quewait $cls $s $timeout] + return filter_ok +} + +# Callback to send/recv request to search server, storing result in CLS. +proc dosearch.quewait {cls s timeout why} { + switch $why { + writable { + puts $s "... send some search result ..." + flush $s + ns_quewait $s readable $timeout [list dosearch.quewait $cls $s $timeout] + } + readable { + set result [gets $s] + ns_cls set $cls $results + } + dropped - + timeout - + default { + # NB: Clien drop, timeout, or error. + close $s + } + } +} + +# Connection procedure to display results stored in CLS. +ns_register_proc GET /search dosearch.proc $cls + +proc dosearch.proc {cls} { + ns_return 200 text/html "done: [ns_cls get $cls]" +} + +.CE + +.SH "SEE ALSO" +Ns_QueueWait(3), ns_cls(n), ns_register_filter(n) + +.SH KEYWORDS +callback diff --git a/doc/ns_tls.n b/doc/ns_tls.n new file mode 100644 index 0000000..c9a5960 --- /dev/null +++ b/doc/ns_tls.n @@ -0,0 +1,83 @@ +'\" +'\" 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_tls.n,v 1.1 2009/12/08 04:13:18 jgdavidson Exp $ +'\" +'\" +.so man.macros + +.TH ns_tls n 4.6 AOLserver "AOLserver Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +ns_tls \- thread local storage command +.SH SYNOPSIS +\fBns_tls \fBalloc\fR +.sp +\fBns_tls \fget\fR \fIid\fR +.sp +\fBns_tls \fset\fR \fIid\fR \fIstring\fR +.BE + +.SH DESCRIPTION +.PP +The \fBns_tls\fR command provides Tcl-level access to the \fBNs_Tls\fR +thread-local storage interface to manage data private to a thread +and independent of the calling interpreter. + +.PP +Normally Tcl global variables can be used to manage private data +as interpreters are bound to threads. The \fBns_tls\fR command is +provided for special cases where data needs to be shared among +multiple interpreters in the same thread or between invocations of +Tcl-script callbacks where the interpreter is re-initalized after +each call (e.g., \fBns_sockcallback\fR). + +.SH USAGE +.PP +With the \fBalloc\fR option, \fBns_tls\fR returns a unique integer +indentifier later used with the \fBget\fR and \fBset\fR options. +It is only safe to call \fBns_tls alloc\fR at server startup. The +resulting \fIid\fR can be passed as an argument to callback +registration routines, e.g., \fBns_register_filter\fR and +\fBns_register_proc\fR. + +.PP +The \fBset\fR and \fBget\fR options use the \fIid\fR returned by +\fBalloc\fR to store and retrieve strings unique to the active +connection, respectively. Space utilized for storage of the string +is automatically reclaimed when modified or when the thread exits. + +.SH "SEE ALSO" +Ns_ClsAlloc(3), Ns_ClsGet(3), Ns_ClsSet(3), +Ns_TlsAlloc(3), Ns_TlsGet(3), Ns_TlsSet(3), +ns_sockcallback(n), ns_register_filter(n), ns_register_proc(n), + +.SH KEYWORDS +callback, thread