Index: ossp-pkg/sio/sio.pod
RCS File: /v/ossp/cvs/ossp-pkg/sio/sio.pod,v
rcsdiff -q -kk '-r1.1' '-r1.2' -u '/v/ossp/cvs/ossp-pkg/sio/sio.pod,v' 2>/dev/null
--- sio.pod	2002/11/07 15:29:08	1.1
+++ sio.pod	2002/11/08 10:36:35	1.2
@@ -121,6 +121,7 @@
  SIO_UPSTREAM   Invoke Upstream Stage
  SIO_DOWNSTREAM Invoke Downstream Stage
  SIO_XSTREAM    Invoke Crossstream Stage
+ SIO_LOOP       Loop through current Stage
 
 =item B<sio_mode_t> (Attach Mode Type)
 
@@ -347,7 +348,8 @@
 used to force either direction, the standard code B<SIO_OK> lets the
 scheduler determine the direction depending on the input assembly line.
 The special return code B<SIO_XSTREAM> will schedule the corresponding
-output side of the stream.
+output side of the stream and the code B<SIO_LOOP> instructs the
+scheduler to call the same stage again.
 Any other code will abort the scheduler and leave the stream in an
 inconsistent state.
 
@@ -359,7 +361,8 @@
 used to force either direction, the standard code B<SIO_OK> lets the
 scheduler determine the direction depending on the input assembly line.
 The special return code B<SIO_XSTREAM> will schedule the corresponding
-input side of the stream.
+input side of the stream and the code B<SIO_LOOP> instructiosn the
+scheduler to call the same stage again.
 Any other code will abort the scheduler and leave the stream in an
 inconsistent state.
 
@@ -387,6 +390,157 @@
 that directs the scheduler back to the originating side to
 keep I/O semantics consistent.
 
+=head2 Stage Modules
+
+=over 4
+
+=item Private data per instance
+
+Private data needs to be encapsuled into a structure that can
+be referenced with a single pointer.
+
+ typedef struct {
+     int a;
+     float b;
+     char *c;
+ } private_t;
+
+ static
+ sio_rc_t XXX_init(sio_t *sio, void **up) {
+
+     private_t *my;
+
+     my = (private_t *)malloc(sizeof(private_t));
+     if (my == NULL)
+         return SIO_ERR_MEM;
+
+     /* initialize private data... */
+
+     /* pass back to SIO, the pointer will be passed
+      * to every other function in the module.
+      */
+     *up = my;
+     return SIO_OK;
+ }
+
+The init function is called when the stage is created with
+B<sio_create_stage> and a corresponding cleanup function is called
+when the stage is detroyed with B<sio_destroy_stage>.
+
+ static
+ sio_rc_t XXX_cleanup(sio_t *sio, void *u)
+ {
+     private_t *my = (private_t *)u;
+
+     /* deinitialize private data... */
+
+     /* free memory */
+     free(my);
+
+     return SIO_OK;
+ }
+
+Most stages require parameters to complete initialization. These
+parameters are passed through B<sio_configure_stage> to the
+configure function of the module.
+
+ static
+ sio_rc_t XXX_configure(sio_t *sio, void *u, void *o, void *v)
+ {
+     private_t *my = (private_t *)u;
+     const char *name = (const char *)o;
+
+     if (strcmp(name, "parameter1") == 0) {
+         /* fetch parameter by reference */
+         int par1 = *(int *)v;
+         /* store parameter1 */
+         my->a = par1;
+     } elsif (strcmp(name, "parameter2") == 0) {
+         /* fetch parameter by reference */
+         float par2 = *(float *)v;
+         /* store parameter2 */
+         my->b = par2;
+     } elsif (strcmp(name, "parameter2") == 0) {
+         /* XXX - fetch parameter by value */
+         char *par3 = (char *)v;
+         /* store parameter2 */
+         my->c = par3;
+     } else {
+         return SIO_ERR_ARG;
+     }
+
+     return SIO_OK;
+ }
+
+=item Attaching and detaching stages
+
+A data pipe consists of one or more processing nodes, that operate
+on a shared B<OSSP al> assembly line. B<OSSP sio> will call the
+corresponding B<sios-E<gt>openr> and B<sios-E<gt>openw> functions
+before attaching a node to the input pipe or the output pipe
+respectively.
+The functions B<sios-E<gt>closer> and B<sios-E<gt>closew> are
+then called after detaching a node.
+
+=item Input and Output
+
+The input and output functions of all stages on a data pipe are
+called by a scheduler which is started by calling the API functions
+B<sio_input> and B<sio_output>. The scheduler first calls the
+bottom-most stage which then returns a special status code
+to direct the scheduler either upstream to the next stage
+or downstream to the previous stage.
+
+The standard action of an input stage is to push data downstream:
+
+ if (can deliver data)
+     put data on assembly line
+     return SIO_DOWNSTREAM
+ else
+     return SIO_UPSTREAM
+
+The standard action of an output stage is the reverse to push
+data upstream:
+
+ if (can deliver data)
+     put data on assembly line
+     return SIO_UPSTREAM
+ else
+     return SIO_DOWNSTREAM
+
+In many situations this can be handled by the scheduler:
+
+ put data on assembly line
+ return SIO_OK
+
+which then interprets any data on the assembly line as
+ready to be delivered.
+
+=item Top-Most Stage
+
+The top-most stage behaves differently since it has no
+upstream peer to send data to or fetch data from. Instead
+it needs to discard output data and block until it can
+deliver data. The only valid return code is therefore
+SIO_DOWNSTREAM.
+
+=item Standard Input and Output
+
+The basic <OSSP sio> operation does not support failure
+modes, in particular: end-of-file conditions and errors.
+This is implemented on top using the <OSSP al> data labelling
+capability.
+
+=item Full-Duplex Protocol Operation
+
+The two halfs of a <OSSP sio> stream are separated by design:
+B<sio_input> schedules all stages attached to the input
+assembly line and B<sio_output> schedules all stages attached
+to the output assembly line.
+
+
+=back
+
 =head1 SEE ALSO
 
 B<OSSP al>