---------------------
PatchSet 1611 
Date: 2001/02/19 21:39:10
Author: hno
Branch: eventio
Tag: (none) 
Log:
Specification of the new improved network I/O model being implemented.

Members: 
	doc/Programming-Guide/prog-guide.sgml:1.9->1.9.8.1 

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
retrieving revision 1.9.8.1
diff -u -r1.9 -r1.9.8.1
--- squid/doc/Programming-Guide/prog-guide.sgml	31 Jan 2001 22:20:26 -0000	1.9
+++ squid/doc/Programming-Guide/prog-guide.sgml	19 Feb 2001 21:39:10 -0000	1.9.8.1
@@ -2,7 +2,7 @@
 <article>
 <title>Squid Programmers Guide</title>
 <author>Duane Wessels, Squid Developers
-<date>$Id: prog-guide.sgml,v 1.9 2001/01/31 22:20:26 hno Exp $</date>
+<date>$Id: prog-guide.sgml,v 1.9.8.1 2001/02/19 21:39:10 hno Exp $</date>
 
 <abstract>
 Squid is a WWW Cache application developed by the National Laboratory
@@ -2988,4 +2988,175 @@
 that pointer was last accessed.  If there is a leak, then the bug
 occurs somewhere after that point of the code.
 
+<sect>Network I/O
+
+<p>
+	The networking I/O layer is responsible for all network I/O (duh!).
+
+<p>
+	It is implemented as a set of asyncronous operations for opening /
+	acception connections and reading/writing data on those connections.
+	The asyncronous operation means that each API call will only initiate
+	the operation, and when the operation s finished a supplied callback
+	function will be called.
+
+<p>
+	Created filehandles are cbdata enabled, and any links / pointers to
+	filehandles should be properly managed as cbdata. 
+
+<p>
+	The return value of is 0 on success or -1 on error. On error, errno
+	will be set to a suitable error code.
+
+<sect1>API
+
+<sect2>ncomm_close
+
+<p><verb>
+	int
+	ncomm_close(filehandle *fh);
+</verb>
+
+<p>
+	Closes down the socket once all pending data has been sent.
+
+<sect2>ncomm_abort
+
+<p><verb>
+	int
+	ncomm_abort(filehandle *fh);
+</verb>
+
+<p>
+	Aborts the given network connection immediately. Any pending I/O
+	requests will be aborted.
+
+<sect2>ncomm_listen
+
+<p><verb>
+	int
+	ncomm_listen(int sock_type, int proto, struct sockaddr *where, int addrsize, COMMNEWCB *callback, void *cbdata)
+</verb>
+
+<p>
+	start listening for new connections on the given address/port.
+
+<sect2>ncomm_accept
+
+<p><em/preleminary draft:/ This should probably only accept one connection.
+
+<p><verb>
+	int
+	ncomm_accept(int sock_type, int proto, struct sockaddr *where, struct sockaddr *from, int addrsize, COMMNEWCB callback, void *cbdata)
+</verb>
+
+<p>
+	Like comm_listen, but only accept connections from the given source
+
+<sect2>ncomm_connect
+
+<p><verb>
+	int
+	ncomm_connect(int sock_type, int proto, const struct sockaddr *local, const struct sockaddr *remote, int addrsize, COMMNEWCB *callback, void *data)
+</verb>
+
+<p>
+	Creates a new network connection to the given remote address,
+	optionally using a specified local source address.
+
+<sect2>ncomm_read
+
+<p><verb>
+	void
+	ncomm_read(filehandle *fh, IOBUF *buf, size_t min_size, size_t max_size, COMMIOCB *callback, void *data);
+</verb>
+
+<p>
+	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.
+
+<p>
+	Any errors will be signalled to the callback function.
+
+<sect2>ncomm_write
+
+<p><verb>
+	void
+	ncomm_write(filehandle *fh, IOBUF *buf, off_t offset, size_t size, COMMIOCB *callback, void *data);
+</verb>
+
+<p>
+	request to write some data.
+
+<p>
+	if size is 0 then all data in the buffer will be written.
+
+<p>
+	it is allowable to queue more write requests before the first has
+	finished. The requests will be processed in the order requested.
+
+<p>
+	Any errors will be signalled to the callback function.
+
+<sect2>ncomm_add_close_handler
+
+<p><verb>
+	int
+	ncomm_add_close_handler(filehandle *fh, COMMCLOSECB *handler, void *cbdata);
+</verb>
+
+<p>
+	Registers a close handler what will be called when the socket is closed.
+	For example to clean up associated data structures or keep relations
+	proper.
+
+<sect2>ncomm_abort_all_connections
+
+<p><em/DO WE REALLY NEED THIS?/
+
+<p><verb>
+	void
+	ncomm_abort_all_connections(void);
+</verb>
+
+<p>
+	Aborts all currently open network connections.
+
+<sect1>callbacks
+
+<sect2>COMMNEWCB
+
+<p><verb>
+	typedef void
+	COMMNEWCB(filehandle *fh, struct sockaddr *local, struct sockaddr *peer, void *cbdata);
+</verb>
+
+<p>
+	Called when a new filehandle is created (ncomm_listen / ncomm_accept
+	/ ncomm_connect)
+
+<sect2>COMMIOCB
+
+<p><verb>
+	typedef void
+	COMMIOCB(filehandle *fh, IOBUF *buf, int offset, int size, int errno, void *cbdata);
+</verb>
+
+<p>
+	Called when an I/O operation has finished.
+
+<p>
+	On error, errno will be set to the error verb.
+
+<sect2>COMMCLOSECB
+
+<p><verb>
+	typedef void
+	COMMCLOSECB(filehandle *fh, void *cbdata);
+</verb>
+
+<p>
+	Called when the filehandle is closed (ncomm_close / ncomm_abort), as
+	requested (ncomm_add_close_handler)
+
 </article>