documentation patch - st_netfd_t and nonblocking i/o

Dear state-threads-devel,

Here is a preliminary patch for the documentation, which should help
users avoid the confusion I reported earlier. Notes: I mentioned some
of the things that the _st_netfd_t data structure contains because I
thought it would be good to explain why there is a separate data
structure in the first place, why State Threads doesn't use file
descriptors instead; but you might want to leave this part out.

Also, I think it would be good to clarify the meaning of the following
paragraph in notes.html : "The State Threads architecture uses
non-blocking network I/O for concurrent processing of multiple user
connections. This architecture has a drawback: the entire process and
all its threads may block for the duration of a disk I/O operation
(this is applicable mostly to disk reads; disk writes are usually
performed asynchronously -- data goes to the buffer cache to be
written to disk later)." 

Would it still be correct if we replaced "network I/O" with "netfd
I/O" and "disk I/O" with "normal fd I/O"? If so, maybe we should say
that it is _intended_ to be used this way for disk and network I/O, to
avoid making people think that it differentiates each type of I/O
internally, which I don't think it does (at least from what Gene told
me).

Frederik

--- reference.html	2001-10-31 20:37:24.000000000 -0800
+++ new-reference.html	2002-09-30 08:00:25.000000000 -0700
@@ -235,9 +235,19 @@
 <P>
 <H5>Description</H5>
 
-This datatype represents any open end point of network communication (socket,
-end point of a pipe, FIFO, etc.). Objects of this type are identified by
-a pointer to an opaque data structure.
+Objects of type <B>st_netfd_t</B> are used by the
+State Threads I/O functions in place of file descriptors. These are
+intended to represent the endpoints of network communications - hence
+the name <I>netfd</I> - but they can be created with <A
+HREF=#netfd_open>st_netfd_open</A> to encapsulate any open file
+descriptor, not just those corresponding to sockets. The objects are
+identified by an opaque pointer to an abstract data structure which
+holds, among other things, the file descriptor, a per-descriptor
+private data pointer (see <A
+HREF=#netfd_setspecific>st_netfd_setspecific</A> and <A
+HREF=#netfd_getspecific>st_netfd_getspecific</A>), and synchronization
+flags for internal use.
+
 <P>
 <HR>
 <P>
@@ -1374,8 +1384,12 @@
 <H5>Parameters</H5>
 <TT>st_netfd_open()</TT> has the following parameters:<P>
 <TT>osfd</TT><P>
-An open OS file descriptor obtained from a<TT> pipe(2), socket(3),
-socketpair(3), fcntl(2), dup(2),</TT> etc. call.
+
+Any open OS file descriptor; can be obtained from calls to
+functions including, but not restricted to, <TT>pipe(2), socket(3),
+socketpair(3), fcntl(2), dup(2),</TT> etc.
+
+
 <P>
 <H5>Returns</H5>
 Upon successful completion, a new file descriptor object identifier is
@@ -1384,11 +1398,28 @@
 <P>
 <H5>Description</H5>
 This function creates a new file descriptor object of type
-<A HREF=#netfd_t><B>st_netfd_t</B></A> which represents an open end
-point of network communication.<P>
-<B>Note:</B> Among other things, this function sets a non-blocking flag
-on the underlying OS file descriptor. You should not modify this flag
-directly.
+<A HREF=#netfd_t><B>st_netfd_t</B></A>.<P>
+
+<B>Note:</B> Among other things, this function sets a non-blocking
+flag on the underlying OS file descriptor. You should not modify this
+flag directly. Also, once an <A HREF=#netfd_t><B>st_netfd_t</B></A>
+has been created with a given file descriptor, you should avoid
+passing that descriptor to normal I/O or stdio functions. Since the
+O_NONBLOCK flag is shared across <TT>dup(2)</TT>, this applies to
+<TT>dup()</TT>'ed file descriptors as well - for instance, if you pass
+standard output or standard input to <TT>st_netfd_open()</TT>, then
+you should use <A HREF=#write>st_write()</A> instead of <TT>write</TT>
+or <TT>fprintf</TT> when writing to standard error as well - since all
+three descriptors could point to the same terminal. If necessary, you
+can still use <TT>write</TT> directly if you remember to check
+<TT>errno</TT> for <TT>EAGAIN</TT>, but <TT>fprintf</TT> and other
+stdio functions should be avoided completely because, at least on
+Linux, the stdio library cannot be made to work reliably with
+non-blocking files. (This only applies to file descriptors which are
+passed to <TT>st_netfd_open()</TT> or <A
+HREF=#netfd_open_socket>st_netfd_open_socket()</A>, or which are
+related to such descriptors through <TT>dup()</TT>; other file
+descriptors are untouched by State Threads.)
 <P>
 <HR>
 <P>
@@ -1426,6 +1457,7 @@
 <A HREF=#netfd_open>st_netfd_open()</A>.<P>
 <B>Note:</B> Among other things, this function sets a non-blocking flag
 on the underlying OS socket. You should not modify this flag directly.
+See <A HREF=#netfd_open>st_netfd_open()</A>.
 <P>
 <HR>
 <P>


-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf