ossp-pkg/sio/sio.pod
1.1
##
## OSSP sio - Stream I/O
## Copyright (c) 2002 The OSSP Project <http://www.ossp.org/>
## Copyright (c) 2002 Cable & Wireless Deutschland <http://www.cw.com/de/>
## Copyright (c) 2002 Ralf S. Engelschall <rse@engelschall.com>
## Copyright (c) 2002 Michael van Elst <mlelstv@dev.de.cw.net>
##
## 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<OSSP sio> - Stream I/O
=head1 VERSION
B<OSSP SIO SIO_VERSION_STR>
=head1 SYNOPSIS
=over 4
=item B<Abstract Data Types>:
sio_rc_t,
sio_mode_t,
sio_flag_t,
sio_t,
sio_stage_t,
sio_module_t,
sio_labelnum_t.
=item B<Stream Operations>:
sio_create,
sio_destroy,
sio_input,
sio_output,
sio_read,
sio_write,
sio_push,
sio_flag,
sio_clearflag.
=item B<Stage Operations>:
sio_create_stage,
sio_destroy_stage,
sio_configure_stage,
sio_attach,
sio_detach.
=item B<Error Handling>:
sio_error.
=item B<Internal Stage Operations>:
sio_label,
sios->init,
sios->configure,
sios->cleanup,
sios->openr,
sios->closer,
sios->openw,
sios->closew,
sios->input,
sios->output.
=back
=head1 DESCRIPTION
B<OSSP sio> 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<OSSP sio> uses six data types in its API:
=over 4
=item B<sio_rc_t> (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<sio_mode_t> (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<sio_mode_t> (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<sio_t> (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<sio_stage_t> (Stream Stage Type)
This is an opaque pointer type representing a processing node on
a data pipe.
=item B<sio_module_t> (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<sio_labelnum_t> (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<OSSP sio> provides a bunch of API functions, all modelled after the
same prototype: "C<sio_rc_t> C<sio_>I<name>C<(sio__t *,>...C<)>".
This means every function returns C<sio_rc_t> to indicate its
success (C<SIO_OK>) or failure (C<SIO_ERR_XXX>) by returning a return code
(the corresponding describing text can be determined by passing this
return code to C<sio_error>). Each function name starts with the common
prefix C<sio_> and receives a C<sio_t> object on which it operates as
its first argument.
=head2 Stream Operations
=over 4
=item sio_rc_t B<sio_create>(sio_t **I<siop>);
Create a stream object. The object is stored in I<siop> on success.
=item sio_rc_t B<sio_destroy>(sio_t *I<sio>);
Destroy the stream object I<sio>. The object is invalid after this
call succeeded.
=item sio_rc_t B<sio_input>(sio_t *I<sio>, al_t *I<al>, size_t limit);
Pull data from stream object I<sio>, the data is appended to the
assembly line I<al> and will contain no more than I<limit> bytes.
=item sio_rc_t B<sio_output>(sio_t *I<sio>, al_t *I<al>);
Push data to stream object I<sio>, the data is spliced from the
assembly line I<al>. When the stream has no place for all data
in the assembly line then part (or all) of it will stay in I<al>.
=item sio_rc_t B<sio_read>(sio_t *I<sio>, char *I<dst>, size_t I<n>, size_t *<actualp>);
Copy up to I<n> user data bytes from stream I<sio> and store them into
the buffer I<dst>. The actual number of bytes copied is stored in I<actualp>.
Error chunks and end-of-file chunks passing down the stream will set
the corresponding flags and can be queried with B<sio_flag>.
=item sio_rc_t B<sio_write>(sio_t *I<sio>, char *I<src>, size_t I<n>, size_t *<actualp>);
Copy I<n> bytes from buffer I<src> to stream object I<sio>. I<actualp>
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_push>(sio_t *I<sio>);
Push an end-of-file chunk up the stream I<sio> to trigger stages
to flush internal buffers. It depends on the stages wether they
honor this request.
=item int B<sio_flag>(sio_t *I<sio>, sio_flag_t I<fl>);
Query internal flags of the stream I<sio>. Currently you can
specify the flags B<SIO_FLAG_ERROR> and B<SIO_FLAG_EOF>. The
return value should be treated as a boolean.
=item int B<sio_clearflag>(sio_t *I<sio>, sio_flag_t I<fl>);
Clear internal flags of the stream I<sio>. Currently you can
specify the flags B<SIO_FLAG_ERROR> and B<SIO_FLAG_EOF>. The
function returns the previous state of the flag.
=back
=head2 Stage Operations
=over 4
=item sio_rc_t B<sio_create_stage>(sio_t *I<sio>, sio_module_t *<siom>, sio_stage_t **I<siosp>);
Create a stage object for processing data in stream I<sio> using methods
from module I<siom>. The object is stored in I<siosp> on success.
=item sio_rc_t B<sio_destroy_stage>(sio_t *I<sio>, sio_stage_t *I<sios>);
Destroy the stage object I<sios>. The object is invalid after this call
succeeded.
=item sio_rc_t B<sio_configure_stage>(sio_t *I<sio>, sio_stage_t *I<sios>, void *I<o>, void *I<v>);
Pass additional data to stage object I<sios>. The data is specific to
the stage and passed as two void pointers. Most stages will cast
I<o> to a const char * and interpret it as a parameter name and will
cast I<v> to a pointer to the value of that parameter.
=back
=head2 Error Handling
=over 4
=item const char *B<sio_error>(sio_rc_t I<rv>);
Retrieve a string that describes the return code I<rv> in english.
=back
=head2 B<Internal Stage Operations>:
The I<sio_label> 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_label>(sio_t *I<sio>, sio_labelnum_t I<ln>, al_label_t *<labelp>);
Map the generic B<OSSP sio> data label number I<ln> to a B<OSSP al> label
value and store the result in I<labelp>.
=back
A stage module implements the following functions and exports them
in a global I<sio_module_t> 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<sio_create_stage>.
=over 4
=item sio_rc_t B<sios-E<gt>init>(sio_t *I<sio>, void **I<up>);
Initialize a stage, a pointer to private per-instance data
will be stored in I<up> and will be passed to the subsequent
methods.
=item sio_rc_t B<sios-E<gt>configure>(sio_t *I<sio>, void *I<u>, void *I<o>, void *I<v>);
Pass additional data to a stage. The data is specific to
the stage and passed as two void pointers. Most stages will cast
I<o> to a const char * and interpret it as a parameter name and will
cast I<v> to a pointer to the value of that parameter.
=item sio_rc_t B<sios-E<gt>cleanup>(sio_t *I<sio>, void *I<u>);
Deinitialize a stage and free all ressources allocated at init time.
=item sio_rc_t B<sios-E<gt>openr>(sio_t *I<sio>, al_t *I<al>, void *I<u>);
Open a stage for reading. The stage will be attached at the stream
top on success.
=item sio_rc_t B<sios-E<gt>closer>(sio_t *I<sio>, al_t *I<al>, void *I<u>);
Close a stage for reading and free all ressources allocated at openr time.
=item sio_rc_t B<sios-E<gt>openw>(sio_t *I<sio>, al_t *I<al>, void *I<u>);
Open a stage for writing. The stage will be attached at the stream
top on success.
=item sio_rc_t B<sios-E<gt>closew>(sio_t *I<sio>, al_t *I<al>, void *I<u>);
Close a stage for writing and free all ressources allocated at openw time.
=item sio_rc_t B<sios-E<gt>input>(sio_t *I<sio>, al_t *I<al>, void *I<u>);
Transport data downstream to a reader, if there is no data then pull
more from upstream stages.
The special return codes B<SIO_UPSTREAM> and B<SIO_DOWNSTREAM> can be
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.
Any other code will abort the scheduler and leave the stream in an
inconsistent state.
=item sio_rc_t B<sios-E<gt>output>(sio_t *I<sio>, al_t *I<al>, void *I<u>);
Transport data upstream from a writer. if there is no data then request
more data from downstream stages.
The special return codes B<SIO_UPSTREAM> and B<SIO_DOWNSTREAM> can be
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.
Any other code will abort the scheduler and leave the stream in an
inconsistent state.
=back
=head1 THEORY
A B<OSSP sio> stream is a pair of two half-duplex data pipes. Each data
pipe consists of an B<OSSP al> 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<OSSP al>
=head1 HISTORY
B<OSSP sio> was invented in October 2002 by Michael van Elst
E<lt>mlelstv@dev.de.cw.netE<gt> under contract with Cable & Wireless
Germany E<lt>http://www.cw.com/deE<gt> for use inside the OSSP project
E<lt>http://www.ossp.org/E<gt>.
=head1 AUTHORS
Michael van Elst
mlelstv@dev.de.cw.net
=cut
