Index: ossp-pkg/sio/sio.pod RCS File: /v/ossp/cvs/ossp-pkg/sio/sio.pod,v co -q -kk -p'1.1' '/v/ossp/cvs/ossp-pkg/sio/sio.pod,v' | diff -u /dev/null - -L'ossp-pkg/sio/sio.pod' 2>/dev/null --- ossp-pkg/sio/sio.pod +++ - 2024-05-19 00:16:30.315812605 +0200 @@ -0,0 +1,407 @@ +## +## OSSP sio - Stream I/O +## Copyright (c) 2002 The OSSP Project +## Copyright (c) 2002 Cable & Wireless Deutschland +## Copyright (c) 2002 Ralf S. Engelschall +## Copyright (c) 2002 Michael van Elst +## +## This file is part of OSSP al, an abstract datatype of a data buffer +## that can assemble, move and truncate data but avoids actual copying. +## +## Permission to use, copy, modify, and distribute this software for +## any purpose with or without fee is hereby granted, provided that +## the above copyright notice and this permission notice appear in all +## copies. +## +## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED +## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR +## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF +## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +## SUCH DAMAGE. +## +## sio.pod: stream I/O library manual page +## + +=pod + +=head1 NAME + +B - Stream I/O + +=head1 VERSION + +B + +=head1 SYNOPSIS + +=over 4 + +=item B: + +sio_rc_t, +sio_mode_t, +sio_flag_t, +sio_t, +sio_stage_t, +sio_module_t, +sio_labelnum_t. + +=item B: + +sio_create, +sio_destroy, +sio_input, +sio_output, +sio_read, +sio_write, +sio_push, +sio_flag, +sio_clearflag. + +=item B: + +sio_create_stage, +sio_destroy_stage, +sio_configure_stage, +sio_attach, +sio_detach. + +=item B: + +sio_error. + +=item B: + +sio_label, +sios->init, +sios->configure, +sios->cleanup, +sios->openr, +sios->closer, +sios->openw, +sios->closew, +sios->input, +sios->output. + +=back + +=head1 DESCRIPTION + +B defines an abstract type of a pair of half-duplex data pipes. + +It provides the following key features: + +=over 4 + +=back + +=head1 DATA TYPES + +B uses six data types in its API: + +=over 4 + +=item B (Return Code Type) + +This is an exported enumerated integer type with the following possible +values: + + SIO_OK Everything Ok + SIO_ERR_ARG Invalid Argument + SIO_ERR_MEM Not Enough Memory + SIO_ERR_EOF End Of Communication + SIO_ERR_INT Internal Error + SIO_UPSTREAM Invoke Upstream Stage + SIO_DOWNSTREAM Invoke Downstream Stage + SIO_XSTREAM Invoke Crossstream Stage + +=item B (Attach Mode Type) + +This is an exported enumerated integer type with the following possible +values: + + SIO_MODE_INVALID Stage is not attached + SIO_MODE_READ Stage is attached for reading + SIO_MODE_WRITE Stage is attached for writing + SIO_MODE_READWRITE Stage is attached for reading and writing + +=item B (Attach Mode Type) + +This is an exported enumerated integer type with the following possible +values: + + SIO_FLAG_ERROR Identify the error flag + SIO_FLAG_EOF Identify the end-of-file flag + +=item B (Stream I/O Type) + +This is an opaque data type representing apair of two half-duplex data +pipes. Only pointers to this abstract data type are used in the API. + +=item B (Stream Stage Type) + +This is an opaque pointer type representing a processing node on +a data pipe. + +=item B (Stream Stage Module Type) + +This is an opaque data type representing the methods of a stream +stage. Only pointers to this abstract data type are used in the API. + +=item B (Data Label Type) + +This is an exported enumerated integer type with the following possible +values: + + SIO_LN_DATA Label number for user data chunks + SIO_LN_ERROR Label number for error data chunks + SIO_LN_EOF Label number for end-of-file data chunks + +=back + +=head1 FUNCTIONS + +B provides a bunch of API functions, all modelled after the +same prototype: "C CIC<(sio__t *,>...C<)>". +This means every function returns C to indicate its +success (C) or failure (C) by returning a return code +(the corresponding describing text can be determined by passing this +return code to C). Each function name starts with the common +prefix C and receives a C object on which it operates as +its first argument. + +=head2 Stream Operations + +=over 4 + +=item sio_rc_t B(sio_t **I); + +Create a stream object. The object is stored in I on success. + +=item sio_rc_t B(sio_t *I); + +Destroy the stream object I. The object is invalid after this +call succeeded. + +=item sio_rc_t B(sio_t *I, al_t *I, size_t limit); + +Pull data from stream object I, the data is appended to the +assembly line I and will contain no more than I bytes. + +=item sio_rc_t B(sio_t *I, al_t *I); + +Push data to stream object I, the data is spliced from the +assembly line I. When the stream has no place for all data +in the assembly line then part (or all) of it will stay in I. + +=item sio_rc_t B(sio_t *I, char *I, size_t I, size_t *); + +Copy up to I user data bytes from stream I and store them into +the buffer I. The actual number of bytes copied is stored in I. +Error chunks and end-of-file chunks passing down the stream will set +the corresponding flags and can be queried with B. + +=item sio_rc_t B(sio_t *I, char *I, size_t I, size_t *); + +Copy I bytes from buffer I to stream object I. I +stores the actual number of bytes copied in case the stream has no +place for the whole buffer. The bytes will be labeled as user data +inside the stream. + +=item sio_rc_t B(sio_t *I); + +Push an end-of-file chunk up the stream I to trigger stages +to flush internal buffers. It depends on the stages wether they +honor this request. + +=item int B(sio_t *I, sio_flag_t I); + +Query internal flags of the stream I. Currently you can +specify the flags B and B. The +return value should be treated as a boolean. + +=item int B(sio_t *I, sio_flag_t I); + +Clear internal flags of the stream I. Currently you can +specify the flags B and B. The +function returns the previous state of the flag. + +=back + +=head2 Stage Operations + +=over 4 + +=item sio_rc_t B(sio_t *I, sio_module_t *, sio_stage_t **I); + +Create a stage object for processing data in stream I using methods +from module I. The object is stored in I on success. + +=item sio_rc_t B(sio_t *I, sio_stage_t *I); + +Destroy the stage object I. The object is invalid after this call +succeeded. + +=item sio_rc_t B(sio_t *I, sio_stage_t *I, void *I, void *I); + +Pass additional data to stage object I. The data is specific to +the stage and passed as two void pointers. Most stages will cast +I to a const char * and interpret it as a parameter name and will +cast I to a pointer to the value of that parameter. + +=back + +=head2 Error Handling + +=over 4 + +=item const char *B(sio_rc_t I); + +Retrieve a string that describes the return code I in english. + +=back + +=head2 B: + +The I method is used internally by stages that implement +a standard I/O model where data and signalling events (error, end-of-file) +are sent synchronously within the data stream. + +=over 4 + +=item sio_rc_t B(sio_t *I, sio_labelnum_t I, al_label_t *); + +Map the generic B data label number I to a B label +value and store the result in I. + +=back + +A stage module implements the following functions and exports them +in a global I variable which is declared as following: + + typedef struct { + const char *name; + sio_rc_t (*init) (sio_t *, void **); + sio_rc_t (*configure) (sio_t *, void *, void *, void *); + sio_rc_t (*cleanup) (sio_t *, void *); + sio_rc_t (*openr) (sio_t *, al_t *, void *); + sio_rc_t (*closer) (sio_t *, al_t *, void *); + sio_rc_t (*openw) (sio_t *, al_t *, void *); + sio_rc_t (*closew) (sio_t *, al_t *, void *); + sio_rc_t (*input) (sio_t *, al_t *, void *); + sio_rc_t (*output) (sio_t *, al_t *, void *); + } sio_module_t; + +Applications reference this variable to create stage intances with +B. + +=over 4 + +=item sio_rc_t Binit>(sio_t *I, void **I); + +Initialize a stage, a pointer to private per-instance data +will be stored in I and will be passed to the subsequent +methods. + +=item sio_rc_t Bconfigure>(sio_t *I, void *I, void *I, void *I); + +Pass additional data to a stage. The data is specific to +the stage and passed as two void pointers. Most stages will cast +I to a const char * and interpret it as a parameter name and will +cast I to a pointer to the value of that parameter. + +=item sio_rc_t Bcleanup>(sio_t *I, void *I); + +Deinitialize a stage and free all ressources allocated at init time. + +=item sio_rc_t Bopenr>(sio_t *I, al_t *I, void *I); + +Open a stage for reading. The stage will be attached at the stream +top on success. + +=item sio_rc_t Bcloser>(sio_t *I, al_t *I, void *I); + +Close a stage for reading and free all ressources allocated at openr time. + +=item sio_rc_t Bopenw>(sio_t *I, al_t *I, void *I); + +Open a stage for writing. The stage will be attached at the stream +top on success. + +=item sio_rc_t Bclosew>(sio_t *I, al_t *I, void *I); + +Close a stage for writing and free all ressources allocated at openw time. + +=item sio_rc_t Binput>(sio_t *I, al_t *I, void *I); + +Transport data downstream to a reader, if there is no data then pull +more from upstream stages. +The special return codes B and B can be +used to force either direction, the standard code B lets the +scheduler determine the direction depending on the input assembly line. +The special return code B will schedule the corresponding +output side of the stream. +Any other code will abort the scheduler and leave the stream in an +inconsistent state. + +=item sio_rc_t Boutput>(sio_t *I, al_t *I, void *I); + +Transport data upstream from a writer. if there is no data then request +more data from downstream stages. +The special return codes B and B can be +used to force either direction, the standard code B lets the +scheduler determine the direction depending on the input assembly line. +The special return code B will schedule the corresponding +input side of the stream. +Any other code will abort the scheduler and leave the stream in an +inconsistent state. + +=back + +=head1 THEORY + +A B stream is a pair of two half-duplex data pipes. Each data +pipe consists of an B assembly line and a chain of processing +nodes called stages. + +An input operation schedules the stage on the input half, each stage +passes data from the top-most stage downstream to a reader. +The top-most stage needs to a be a producer, e.g. +an object corresponding to a file descriptor open for reading. + +An output operation schedules the stage on the output half, each stage +passes data upstream from a writer to the top-most stage. +The top-most stage needs to be a consumer, e.g. +an object corresponding to a file descriptor open for writing. + +A stage can implement complex protocols by telling the scheduler +to cross sides and invoke the output stage on input operations +and vice versa. The stage must then implement a state machine +that directs the scheduler back to the originating side to +keep I/O semantics consistent. + +=head1 SEE ALSO + +B + +=head1 HISTORY + +B was invented in October 2002 by Michael van Elst +Emlelstv@dev.de.cw.netE under contract with Cable & Wireless +Germany Ehttp://www.cw.com/deE for use inside the OSSP project +Ehttp://www.ossp.org/E. + +=head1 AUTHORS + + Michael van Elst + mlelstv@dev.de.cw.net + +=cut +