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