--- 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>
|
