--------------------- PatchSet 1619 Date: 2001/02/20 21:48:13 Author: hno Branch: eventio Tag: (none) Log: Corrected most of the comments from Alex * clarified when the callbacks will be called * enforced ordering of queued requests * introduced the IOBUF concept * changed the "new" functions (accept/connect) to all return a "dummy" filehandle for the request so it can be aborted before completed * changed ncomm_listen to return a "dummy" filehandle for the listening socket, which can be closed/aborted. * many other minor corrections Members: doc/Programming-Guide/prog-guide.sgml:1.9.8.3->1.9.8.4 Index: squid/doc/Programming-Guide/prog-guide.sgml =================================================================== RCS file: /cvsroot/squid-sf//squid/doc/Programming-Guide/prog-guide.sgml,v retrieving revision 1.9.8.3 retrieving revision 1.9.8.4 diff -u -r1.9.8.3 -r1.9.8.4 --- squid/doc/Programming-Guide/prog-guide.sgml 19 Feb 2001 22:35:43 -0000 1.9.8.3 +++ squid/doc/Programming-Guide/prog-guide.sgml 20 Feb 2001 21:48:13 -0000 1.9.8.4 @@ -2,7 +2,7 @@
Squid Programmers Guide Duane Wessels, Squid Developers -$Id: prog-guide.sgml,v 1.9.8.3 2001/02/19 22:35:43 hno Exp $ +$Id: prog-guide.sgml,v 1.9.8.4 2001/02/20 21:48:13 hno Exp $ Squid is a WWW Cache application developed by the National Laboratory @@ -3008,6 +3008,12 @@ The return value of is 0 on success or -1 on error. On error, errno will be set to a suitable error code. +

+ All data is contained in IOBUF handlers. Each IOBUF has a reference + count, knows the amount of data stored in the IOBUF, actual size + of the allocated buffer area (internal) and the buffer area itself. + IOBUF is not a simple pointer. + API ncomm_close @@ -3018,7 +3024,11 @@

- Closes down the socket once all pending data has been sent. + Closes down the socket once all pending data has been sent (and + acknowledged via callbacks) + +

+ Any pending reads will be cancelled without any callback ncomm_abort @@ -3029,12 +3039,13 @@

Aborts the given network connection immediately. Any pending I/O - requests will be aborted. + requests will be aborted. No callbacks will be done for + cancelled I/O requests. ncomm_listen

- int + filehandle * ncomm_listen(int sock_type, int proto, struct sockaddr *where, int addrsize, COMMNEWCB *callback, void *cbdata) @@ -3042,24 +3053,33 @@

start listening for new connections on the given address/port. -ncomm_accept +

+ The listening port is open until closed with ncomm_close or aborted + with ncomm_abort. comm_abort will cancel any pending queued incoming + connections not yet notified to the callback, while ncomm_close will + only stop listening for new connection requests. -

ncomm_accept

- int + filehandle * ncomm_accept(int sock_type, int proto, struct sockaddr *where, struct sockaddr *from, int addrsize, COMMNEWCB callback, void *cbdata)

- Like comm_listen, but only accept connections from the given source + Accept a single connection from the given source + +

+ The returned filehandle is not valid for use until the callback + has been notified, except for comm_abort to cancel the connection + request. ncomm_connect

- int + filehandle * ncomm_connect(int sock_type, int proto, const struct sockaddr *local, const struct sockaddr *remote, int addrsize, @@ -3070,15 +3090,26 @@ Creates a new network connection to the given remote address, optionally using a specified local source address. +

+ The returned filehandle is not valid for use until the callback + has been notified, except for comm_abort to cancel the connection + request. + ncomm_read -

void +

+ void ncomm_read(filehandle *fh, IOBUF *buf, size_t min_size, - size_t max_size, COMMIOCB *callback, void *data); + size_t max_size, COMMIOCB *callback, void *data); + + +

+ Reads at least min_size or at most max_size of data from the + connection and adds it to the specified IOBUF

- request to read some data. buf might be specified as NULL in which case - a IOBUF will be allocated to keep the data read from the network. + buf might be specified as NULL in which case a new IOBUF will be + allocated to for the data read from the network.

Any errors will be signalled to the callback function. @@ -3092,14 +3123,17 @@

- request to write some data. + request to write data. The callback will be called when + the request has finished, or if an unrecoverable error + occurs.

if size is 0 then all data in the buffer will be written.

it is allowable to queue more write requests before the first has - finished. The requests will be processed in the order requested. + finished. The requests will be processed and completed in the order + requested without reordering.

Any errors will be signalled to the callback function. @@ -3175,15 +3209,20 @@

- Called when an I/O operation has finished. + Called when an I/O operation has finished (ncomm_read / + ncomm_write).

On error errno will be set to the error, otherwise errno will be 0.

- Note: The callback might indicate partial completetion with - an error (size >= 0, errno != 0). + offset is the offset in the IOBUF where the data for the operation + starts, and size is the amount of data processed by the operation. + +

+ Note: On error the operation might have been partially completed. In + such case size >= 0 and errno != 0. COMMCLOSECB