--------------------- PatchSet 5211 Date: 2007/08/09 10:24:20 Author: amosjeffries Branch: docs Tag: (none) Log: Some formatting changes to comments. Doxify some descriptive comments in clientStream.cc file. Members: src/clientStream.cc:1.11->1.11.2.1 src/clientStream.h:1.7.28.2->1.7.28.3 Index: squid3/src/clientStream.cc =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/clientStream.cc,v retrieving revision 1.11 retrieving revision 1.11.2.1 diff -u -r1.11 -r1.11.2.1 --- squid3/src/clientStream.cc 28 Apr 2007 22:51:49 -0000 1.11 +++ squid3/src/clientStream.cc 9 Aug 2007 10:24:20 -0000 1.11.2.1 @@ -1,6 +1,6 @@ /* - * $Id: clientStream.cc,v 1.11 2007/04/28 22:51:49 squidadm Exp $ + * $Id: clientStream.cc,v 1.11.2.1 2007/08/09 10:24:20 amosjeffries Exp $ * * DEBUG: section 87 Client-side Stream routines. * AUTHOR: Robert Collins @@ -33,14 +33,19 @@ * */ -/* +/** + \ingroupClientStream + \section A (Coments from Head of clientStream.cc) + \par * A client Stream is a uni directional pipe, with the usual non-blocking * asynchronous approach present elsewhere in squid. * + \par * Each pipe node has a data push function, and a data request function. * This limits flexability - the data flow is no longer assembled at each * step. * + \par * An alternative approach is to pass each node in the pipe the call- * back to use on each IO call. This allows the callbacks to be changed * very easily by a participating node, but requires more maintenance @@ -49,6 +54,7 @@ * changing the pipeline from outside without an additional interface * method to extract the callback and context from the next node. * + \par * One important characteristic of the stream is that the readfunc * on the terminating node, and the callback on the first node * will be NULL, and never used. @@ -62,14 +68,15 @@ CBDATA_TYPE(clientStreamNode); -/* - * TODO: rather than each node undeleting the next, have a clientStreamDelete +/** + * \todo rather than each node undeleting the next, have a clientStreamDelete * that walks the list */ -/* - * clientStream quick notes: - * +/** + \ingroup ClienStream + \section QuickNotes clientStream quick notes: + \par * Each node including the HEAD of the clientStream has a cbdataReference * held by the stream. Freeing the stream then removes that reference * and cbdataFrees every node. @@ -77,6 +84,7 @@ * free when those references are released. * Stream nodes MAY hold references to the data member of the node. * + \par * Specifically - on creation no reference is made. * If you pass a data variable to a node, give it an initial reference. * If the data member is non-null on FREE, cbdataFree WILL be called. @@ -84,22 +92,25 @@ * explicitly setting the stream node data member to NULL and * cbdataReferenceDone'ing it. * + \par * No data member may hold a reference to it's stream node. * The stream guarantees that DETACH will be called before * freeing the node, alowing data members to cleanup. * + \par * If a node's data holds a reference to something that needs to * free the stream a circular reference list will occur. * This results no data being freed until that reference is removed. * One way to accomplish thisObject is to explicitly remove the * data from your own node before freeing the stream. * - * (i.e. - * mycontext = thisObject->data; - * thisObject->data = NULL; - * clientStreamFree (thisObject->head); - * mycontext = NULL; - * return; + \code + mycontext = thisObject->data; + thisObject->data = NULL; + clientStreamFree (thisObject->head); + mycontext = NULL; + return; + \endcode */ /* Local functions */ @@ -120,7 +131,7 @@ return temp; } -/* +/** * Initialise a client Stream. * list is the stream * func is the read function for the head @@ -141,7 +152,7 @@ temp->readBuffer = tailBuffer; } -/* +/** * Doesn't actually insert at head. Instead it inserts one *after* * head. This is because HEAD is a special node, as is tail * This function is not suitable for inserting the real HEAD. @@ -165,7 +176,7 @@ dlinkAddAfter(cbdataReference(temp), &temp->node, list->head, list); } -/* +/** * Callback the next node the in chain with it's requested data */ void @@ -181,7 +192,7 @@ next->callback(next, http, rep, replyBuffer); } -/* +/** * Call the previous node in the chain to read some data */ void @@ -199,7 +210,7 @@ prev->readfunc(prev, http); } -/* +/** * Detach from the stream - only allowed for terminal members */ void @@ -238,7 +249,7 @@ } } -/* +/** * Abort the stream - detach every node in the pipeline. */ void @@ -256,7 +267,7 @@ } } -/* +/** * Call the upstream node to find it's status */ clientStream_status_t Index: squid3/src/clientStream.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/clientStream.h,v retrieving revision 1.7.28.2 retrieving revision 1.7.28.3 diff -u -r1.7.28.2 -r1.7.28.3 --- squid3/src/clientStream.h 9 Aug 2007 05:48:32 -0000 1.7.28.2 +++ squid3/src/clientStream.h 9 Aug 2007 10:24:20 -0000 1.7.28.3 @@ -1,6 +1,6 @@ /* - * $Id: clientStream.h,v 1.7.28.2 2007/08/09 05:48:32 amosjeffries Exp $ + * $Id: clientStream.h,v 1.7.28.3 2007/08/09 10:24:20 amosjeffries Exp $ * * * SQUID Web Proxy Cache http://www.squid-cache.org/ @@ -38,60 +38,62 @@ #include "RefCount.h" /** - * \defgroup ClientStreamAPI Client Streams - * \ingroup Components - -\section Introduction Introduction -\par - A ClientStream implement a unidirectional, non-blocking, - pull pipeline. They allow code to be inserted into the - reply logic on an as-needed basis. For instance, - transfer-encoding logic is only needed when sending a - HTTP/1.1 reply. - - 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. + \defgroup ClientStreamAPI Client Streams + \ingroup Components + \section Introduction Introduction + \par + * A ClientStream implements a unidirectional, non-blocking, + * pull pipeline. They allow code to be inserted into the + * reply logic on an as-needed basis. For instance, + * transfer-encoding logic is only needed when sending a + * HTTP/1.1 reply. + * + \par + * 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. + * + \secton OperationTheory Theory on stream operation + \par + \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 @@ -144,62 +146,66 @@ SQUIDCEXTERN clientStreamNode *clientStreamNew(CSR *, CSCB *, CSD *, CSS *, ClientStreamData); /** - * \ingroup ClientStreamAPI - * \ingroup Callbacks + \ingroup ClientStreamAPI + * * 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. + \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 + \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. + \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 + \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. + \param node 'this' reference for the client stream + \param req MUST NOT be NULL. */ SQUIDCEXTERN void clientStreamDetach(clientStreamNode *node, ClientHttpRequest *req); /** - * \ingroup ClientStreamAPI + \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. + \param node 'this' reference for the client stream + \param req MUST NOT be NULL. */ SQUIDCEXTERN void clientStreamAbort(clientStreamNode *node, ClientHttpRequest *req); /** - * \ingroup ClientStreamAPI + \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. + \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. + \param node 'this' reference for the client stream + \param req MUST NOT be NULL. */ SQUIDCEXTERN clientStream_status_t clientStreamStatus(clientStreamNode *node, ClientHttpRequest *req);