--------------------- PatchSet 5184 Date: 2007/08/08 02:30:59 Author: amosjeffries Branch: docs Tag: (none) Log: Migrate the ClientStreams documentation into the code. Members: doc/Programming-Guide/08_ClientStreams.dox:1.1.2.2->1.1.2.3(DEAD) doc/Programming-Guide/Groups.dox:1.1.2.3->1.1.2.4 src/clientStream.h:1.7->1.7.28.1 --- squid3/doc/Programming-Guide/08_ClientStreams.dox Thu Aug 9 00:19:41 2007 +++ /dev/null Thu Aug 9 00:19:41 2007 @@ -1,126 +0,0 @@ -/** -\page 08_ClientStreams Client Streams - -\todo DOCS: this seems all to be a better fit as inline code comments. - -\section Introduction Introduction -\par - A clientStream is a uni-directional loosely coupled pipe. Each node - consists of four methods - read, callback, detach, and status, along with the - stream housekeeping variables (a dlink node and pointer to the head of - the list), context data for the node, and read request parameters - - readbuf, readlen and readoff (in the body). -\par - clientStream is the basic unit for scheduling, and the clientStreamRead - and clientStreamCallback calls allow for deferred scheduled activity if desired. - -\par Theory on stream operation: - \li Something creates a pipeline. At a minimum it needs a head with a - status method and a read method, and a tail with a callback method and a - valid initial read request. - \li Other nodes may be added into the pipeline. - \li The tail-1th node's read method is called. - For each node going up the pipeline, the node either: - \li satisfies the read request, or - \li inserts a new node above it and calls clientStreamRead, or - \li calls clientStreamRead -\todo DOCS: make the above list nested. - -\par - There is no requirement for the Read parameters from different - nodes to have any correspondence, as long as the callbacks provided are - correct. -\par - The first node that satisfies the read request MUST generate an - httpReply to be passed down the pipeline. Body data MAY be provided. - \li On the first callback a node MAY insert further downstream nodes in - the pipeline, but MAY NOT do so thereafter. - \li The callbacks progress down the pipeline until a node makes further - reads instead of satisfying the callback (go to 4) or the end of the - pipe line is reached, where a new read sequence may be scheduled. - -\section ImplementationNotes Implementation notes -\par - ClientStreams have been implemented for the client side reply logic, - starting with either a client socket (tail of the list is - clientSocketRecipient) or a custom handler for in-squid requests, and - with the pipeline HEAD being clientGetMoreData, which uses - clientSendMoreData to send data down the pipeline. -\par - Client POST bodies do not use a pipeline currently, they use the - previous code to send the data. This is a TODO when time permits. - -\section WhatsInANode Whats in a node - -\todo ClientStreams: These details should really be codified as a class which all ClientStream nodes inherit from. - -\par Each node must have: - \li read method - to allow loose coupling in the pipeline. (The reader may - therefore change if the pipeline is altered, even mid-flow). - \li callback method - likewise. - \li status method - likewise. - \li detach method - used to ensure all resources are cleaned up properly. - \li dlink head pointer - to allow list inserts and deletes from within a node. - \li context data - to allow the called back nodes to maintain their private information. - \li read request parameters - For two reasons: - \li To allow a node to determine the requested data offset, length and target buffer dynamically. Again, this is to promote loose coupling. - \li Because of the callback nature of squid, every node would have to keep these parameters in their context anyway, so this reduces programmer overhead. - -\section MethodDetails Method details -\par - The first parameter is always the 'this' reference for the client stream - a clientStreamNode *. - -\subsection Read Read -\par Parameters: - \li clientHttpRequest * - superset of request data, being winnowed down over time. MUST NOT be NULL. - \li offset, length, buffer - what, how much and where. - -\par Side effects: -\par - Triggers a read of data that satisfies the httpClientRequest - metainformation and (if appropriate) the offset,length and buffer - parameters. - -\subsection Callback Callback -\par Parameters: - \li clientHttpRequest * - superset of request data, being winnowed down over time. MUST NOT be NULL. - \li httpReply * - not NULL on the first call back only. Ownership is passed down the pipeline. Each node may alter the reply if appropriate. - \li buffer, length - where and how much. - -\par Side effects: -\par - Return data to the next node in the stream. The data may be returned immediately, - or may be delayed for a later scheduling cycle. - -\subsection Detach Detach -\par Parameters: - \li clienthttpRequest * - MUST NOT be NULL. - -\par Side effects: - \li Removes this node from a clientStream. The stream infrastructure handles the removal. This node MUST have cleaned up all context data, UNLESS scheduled callbacks will take care of that. - \li Informs the prev node in the list of this nodes detachment. - -\subsection Status Status -\par Parameters: - \li clienthttpRequest * - MUST NOT be NULL. - -\par Side effects: - -\par - Allows nodes to query the upstream nodes for : - \li stream ABORTS - request cancelled for some reason. upstream will not accept further reads(). - \li stream COMPLETION - upstream has completed and will not accept further reads(). - \li stream UNPLANNED COMPLETION - upstream has completed, but not at a pre-planned location (used for keepalive checking), and will not accept further reads(). - \li stream NONE - no special status, further reads permitted. - -\subsection Abort Abort -\par Parameters: - \li clienthttpRequest * - MUST NOT be NULL. - -\par Side effects: - -\par - Detachs the tail of the stream. CURRENTLY DOES NOT clean up the tail node data - - this must be done separately. Thus Abort may ONLY be called by the tail node. - - */ Index: squid3/doc/Programming-Guide/Groups.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/Groups.dox,v retrieving revision 1.1.2.3 retrieving revision 1.1.2.4 diff -u -r1.1.2.3 -r1.1.2.4 --- squid3/doc/Programming-Guide/Groups.dox 12 Jul 2007 22:58:58 -0000 1.1.2.3 +++ squid3/doc/Programming-Guide/Groups.dox 8 Aug 2007 02:30:59 -0000 1.1.2.4 @@ -15,6 +15,11 @@ */ /** + * \defgroup ServerProtocol Server Protocols + * \ingroup Components + */ + +/** * \defgroup libsquid Squid Library * * \par Index: squid3/src/clientStream.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/clientStream.h,v retrieving revision 1.7 retrieving revision 1.7.28.1 diff -u -r1.7 -r1.7.28.1 --- squid3/src/clientStream.h 16 Mar 2003 03:13:58 -0000 1.7 +++ squid3/src/clientStream.h 8 Aug 2007 02:30:59 -0000 1.7.28.1 @@ -1,6 +1,6 @@ /* - * $Id: clientStream.h,v 1.7 2003/03/16 03:13:58 squidadm Exp $ + * $Id: clientStream.h,v 1.7.28.1 2007/08/08 02:30:59 amosjeffries Exp $ * * * SQUID Web Proxy Cache http://www.squid-cache.org/ @@ -37,20 +37,79 @@ #include "StoreIOBuffer.h" #include "RefCount.h" +/** + * \defgroup ClientStreamAPI Client Streams + * \ingroup Components + +\section Introduction Introduction +\par + A clientStream is a uni-directional loosely coupled pipe. Each node + consists of four methods - read, callback, detach, and status, along with the + stream housekeeping variables (a dlink node and pointer to the head of + the list), context data for the node, and read request parameters - + readbuf, readlen and readoff (in the body). +\par + clientStream is the basic unit for scheduling, and the clientStreamRead + and clientStreamCallback calls allow for deferred scheduled activity if desired. + +\par Theory on stream operation: + \li Something creates a pipeline. At a minimum it needs a head with a + status method and a read method, and a tail with a callback method and a + valid initial read request. + \li Other nodes may be added into the pipeline. + \li The tail-1th node's read method is called. +\par + For each node going up the pipeline, the node either: + \li satisfies the read request, or + \li inserts a new node above it and calls clientStreamRead, or + \li calls clientStreamRead +\todo DOCS: make the above list nested. + +\par + There is no requirement for the Read parameters from different + nodes to have any correspondence, as long as the callbacks provided are + correct. + +\section WhatsInANode Whats in a node + +\todo ClientStreams: These details should really be codified as a class which all ClientStream nodes inherit from. + +\par Each node must have: + \li read method - to allow loose coupling in the pipeline. (The reader may + therefore change if the pipeline is altered, even mid-flow). + \li callback method - likewise. + \li status method - likewise. + \li detach method - used to ensure all resources are cleaned up properly. + \li dlink head pointer - to allow list inserts and deletes from within a node. + \li context data - to allow the called back nodes to maintain their private information. + \li read request parameters - For two reasons: + \li To allow a node to determine the requested data offset, length and target buffer dynamically. Again, this is to promote loose coupling. + \li Because of the callback nature of squid, every node would have to keep these parameters in their context anyway, so this reduces programmer overhead. + */ + +/// \ingroup ClientStreamAPI typedef RefCount ClientStreamData; class clientStreamNode; class ClientHttpRequest; + /* client stream read callback */ +/// \ingroup ClientStreamAPI typedef void CSCB(clientStreamNode *, ClientHttpRequest *, HttpReply *, StoreIOBuffer); + /* client stream read */ +/// \ingroup ClientStreamAPI typedef void CSR(clientStreamNode *, ClientHttpRequest *); + /* client stream detach */ +/// \ingroup ClientStreamAPI typedef void CSD(clientStreamNode *, ClientHttpRequest *); -typedef clientStream_status_t CSS(clientStreamNode *, ClientHttpRequest *); +/// \ingroup ClientStreamAPI +typedef clientStream_status_t CSS(clientStreamNode *, ClientHttpRequest *); +/// \ingroup ClientStreamAPI class clientStreamNode { @@ -68,14 +127,73 @@ StoreIOBuffer readBuffer; /* what, where and how much this node wants */ }; -/* clientStream.c */ +/// \ingroup ClientStreamAPI SQUIDCEXTERN void clientStreamInit(dlink_list *, CSR *, CSD *, CSS *, ClientStreamData, CSCB *, CSD *, ClientStreamData, StoreIOBuffer tailBuffer); + +/// \ingroup ClientStreamAPI SQUIDCEXTERN void clientStreamInsertHead(dlink_list *, CSR *, CSCB *, CSD *, CSS *, ClientStreamData); + +/// \ingroup ClientStreamAPI SQUIDCEXTERN clientStreamNode *clientStreamNew(CSR *, CSCB *, CSD *, CSS *, ClientStreamData); -SQUIDCEXTERN void clientStreamCallback(clientStreamNode *, ClientHttpRequest *, HttpReply *, StoreIOBuffer replyBuffer); -SQUIDCEXTERN void clientStreamRead(clientStreamNode *, ClientHttpRequest *, StoreIOBuffer readBuffer); -SQUIDCEXTERN void clientStreamDetach(clientStreamNode *, ClientHttpRequest *); -SQUIDCEXTERN void clientStreamAbort(clientStreamNode *, ClientHttpRequest *); -SQUIDCEXTERN clientStream_status_t clientStreamStatus(clientStreamNode *, ClientHttpRequest *); + +/** + * \ingroup ClientStreamAPI + * \ingroup Callbacks + * Return data to the next node in the stream. + * The data may be returned immediately, or may be delayed for a later scheduling cycle. + * + * \param node 'this' reference for the client stream + * \param req Superset of request data, being winnowed down over time. MUST NOT be NULL. + * \param reply Not NULL on the first call back only. Ownership is passed down the pipeline. + * Each node may alter the reply if appropriate. + * \param replyBuffer - buffer, length - where and how much. + */ +SQUIDCEXTERN void clientStreamCallback(clientStreamNode *node, ClientHttpRequest *req, HttpReply *reply, StoreIOBuffer replyBuffer); + +/** + * \ingroup ClientStreamAPI + * Triggers a read of data that satisfies the httpClientRequest + * metainformation and (if appropriate) the offset,length and buffer + * parameters. + * + * \param node 'this' reference for the client stream + * \param req Superset of request data, being winnowed down over time. MUST NOT be NULL. + * \param readBuffer - offset, length, buffer - what, how much and where. + */ +SQUIDCEXTERN void clientStreamRead(clientStreamNode *node, ClientHttpRequest *req, StoreIOBuffer readBuffer); + +/** + * \ingroup ClientStreamAPI + * Removes this node from a clientStream. The stream infrastructure handles the removal. + * This node MUST have cleaned up all context data, UNLESS scheduled callbacks will take care of that. + * Informs the prev node in the list of this nodes detachment. + * + * \param node 'this' reference for the client stream + * \param req MUST NOT be NULL. + */ +SQUIDCEXTERN void clientStreamDetach(clientStreamNode *node, ClientHttpRequest *req); + +/** + * \ingroup ClientStreamAPI + * Detachs the tail of the stream. CURRENTLY DOES NOT clean up the tail node data - + * this must be done separately. Thus Abort may ONLY be called by the tail node. + * + * \param node 'this' reference for the client stream + * \param req MUST NOT be NULL. + */ +SQUIDCEXTERN void clientStreamAbort(clientStreamNode *node, ClientHttpRequest *req); + +/** + * \ingroup ClientStreamAPI + * Allows nodes to query the upstream nodes for : + * \li stream ABORTS - request cancelled for some reason. upstream will not accept further reads(). + * \li stream COMPLETION - upstream has completed and will not accept further reads(). + * \li stream UNPLANNED COMPLETION - upstream has completed, but not at a pre-planned location (used for keepalive checking), and will not accept further reads(). + * \li stream NONE - no special status, further reads permitted. + * + * \param node 'this' reference for the client stream + * \param req MUST NOT be NULL. + */ +SQUIDCEXTERN clientStream_status_t clientStreamStatus(clientStreamNode *node, ClientHttpRequest *req); #endif /* SQUID_CLIENTSTREAM_H */