_        ___  ____ ____  ____        _       
  |_|_ _   / _ \/ ___/ ___||  _ \   ___(_) ___  
  _|_||_| | | | \___ \___ \| |_) | / __| |/ _ \ 
 |_||_|_| | |_| |___) |__) |  __/  \__ \ | (_) |
  |_|_|_|  \___/|____/____/|_|     |___/_|\___/ 

  OSSP sio - Stream I/O

  TODO

  The following items still have to be done:

  -NONE-

  CANDO

  -NONE-

  FEEDBACK [rse]

  o be consistent in argument order with other sio_stage_t based functions:
    < sio_rc_t    sio_create_stage   (sio_t  *sio, sio_module_t *siom, sio_stage_t **siosp);
    > sio_rc_t    sio_create_stage   (sio_t  *sio, sio_stage_t **siosp, sio_module_t *siom);

  o merge sio_module.h into sio.h because although intended for module writers
    it has to be part of the official/public API. So it belongs to sio.h, too.

  o the following sio_rc_t's have no ERR sub-prefix. Obviously because you treat
    them not really as "errors". Ok, but nevertheless they need a common
    sub-prefix because belong together into an own class of return codes.
    Suggestions: SIO_DO_XXX or SIO_HINT_XXX, etc.
    SIO_UPSTREAM   Invoke Upstream Stage
    SIO_DOWNSTREAM Invoke Downstream Stage
    SIO_XSTREAM    Invoke Crossstream Stage
    SIO_LOOP       Loop through current Stage

  o sio.h haengt von al.h ab wegen References to al_t! 
    Suggestion: forward declaration in sio.h for al_t.

  o sio_push: I expected a different operation by reading "push" here.
    Would perhaps sio_end, sio_finish, sio_close, sio_eof, sio_shutoff,
    etc not more intuitive here?

  o sio_flag und sio_clearflag:
    The return value (int) is inconsistent with the others (sio_rc_t).
    My suggestion:  sa_rc_t sio_setflag(sio_t *sio, sio_flag_t fl);
                    sa_rc_t sio_getflag(sio_t *sio, sio_flag_t fl);
    And the return code for old TRUE is SA_OK and for FALSE is SA_ERR_NEG
    (negative) or something like this.

  o sios->{open,close}{r,w}(): any reason why it's four functions
    and not just two? I intuitively expected just sios->{open,close}()
    with an additional parameter indicating read or write operation.
 
  o sio_configure_stage is unneccesary restrictive in passed data:
    < sio_rc_t    sio_configure_stage(sio_t  *sio, sio_stage_t *sios, void *o, void *v);
    > sio_rc_t    sio_configure_stage(sio_t  *sio, sio_stage_t *sios, void *v, ...);
    < sio_rc_t (*configure) (sio_t *, void *, void *, void *);
    > sio_rc_t (*configure) (sio_t *, void *, void *, va_list ap);
    This way the application can decide itself how it is configured
    and with which parameter stypes and with how much parameters.
  
  o Additionally to make sios->configure implementations easier and to
    reduce complexity and redundancy, I suggest to provide a
    sio_setparams() function which is similar to l2_util_setparams() in
    OSSP l2. This optionally provides the usually required convinience in
    writing stages.