helm/DEVEL/pxp/netstring/netstream.mli

   1 (* $Id$
   2  * ----------------------------------------------------------------------
   3  *
   4  *)
   5
   6
   7 (* A netstream is an input channel that is read block by block. The
   8  * fragment of the channel currently loaded into memory is called the
   9  * current window of the netstream.
  10  *
  11  * PICTURE:
  12  *
  13  * 0            window_position     current_length                  EOS
  14  * +------------------+-------------------+--------------------------+
  15  *                    ====================
  16  *                     The current window
  17  *
  18  * window_length = current_length - window_position
  19  *
  20  * There is an automatism that the window has a certain length. If possible,
  21  * the window is at least twice the block size long, where a "block" is
  22  * the amount of data that is read from the input channel in one step.
  23  *
  24  * (The idea is that you choose as block size the number of bytes you want
  25  * to analyze at once, and which must be loaded into memory. You can start
  26  * your analysis at window_position and proceed until window_position +
  27  * blocksize without having to check whether your window is large enough.
  28  * Only when the first blocksize bytes of the window are already processed,
  29  * the window must be enlarged by loading the next block.)
  30  *
  31  * If you want that the window becomes larger, you can call 'want' (to
  32  * enlarge the window to a certain size) or 'want_another_block' (to load
  33  * just another block from the input channel). Note that this affects only
  34  * the current window and not future windows.
  35  *
  36  * If you do not need the first n bytes of the window anymore, you can
  37  * call 'move' to move the beginning of the window by n bytes. If the
  38  * window becomes too small after this operation, it is enlarged until
  39  * it has twice the block size or until it reaches EOS.
  40  *)
  41
  42 type t
  43
  44 val create_from_channel : in_channel -> int option -> int -> t
  45     (* create_from_channel ch maxlength blocksize:
  46      * The new netstream reads from the channel 'ch'. If maxlength = None,
  47      * the channel is read until EOF. If maxlength = Some n, at most n bytes
  48      * are read; i.e. the netstream reads until n bytes have been read or
  49      * until EOF has been reached, whatever comes first. The blocksize
  50      * specifies the number of bytes to read at once.
  51      *)
  52
  53 val create_from_string : string -> t
  54     (* Creates a new netstream from a string. The initial window of this
  55      * netstream is a copy of the passed string.
  56      *)
  57
  58 val block_size : t -> int
  59    (* Returns the (immutable) block size. *)
  60
  61 val current_length : t -> int
  62     (* Returns the number of bytes read so far. *)
  63
  64 val at_eos : t -> bool
  65     (* True iff EOS (end of stream) is reached, i.e. the last byte of the
  66      * window is the last byte of the stream.
  67      *)
  68
  69 val window_position : t -> int
  70     (* Returns the absolute position of the current window. *)
  71
  72 val window_length : t -> int
  73     (* Returns the length of the current window. *)
  74
  75 val window : t -> Netbuffer.t
  76     (* Returns the current window. *)
  77
  78 val move : t -> int -> unit
  79     (* move s n:
  80      * Moves the window: The first n bytes of the current window are
  81      * discarded. If the window would become smaller than twice the
  82      * blocksize and if the end of the stream is not yet reached, another
  83      * block is read from the input channel and appended to the window.
  84      *
  85      * PRECONDITION:
  86      * - n <= window_length
  87      *)
  88
  89 val want : t -> int -> unit
  90     (* want s n:
  91      * If the window is smaller than n bytes, it is tried to enlarge
  92      * the window such that it is at least n bytes long. The enlargement
  93      * is not possible if the stream is not long enough; in this case
  94      * the window becomes as large as possible.
  95      *)
  96
  97 val want_another_block : t -> unit
  98     (* Enlarges the window by another block (if possible i.e. if the stream
  99      * is long enough).
 100      *)
 101
 102 val print_stream : t -> unit
 103
 104 (* ======================================================================
 105  * History:
 106  *
 107  * $Log$
 108  * Revision 1.1  2000/11/17 09:57:27  lpadovan
 109  * Initial revision
 110  *
 111  * Revision 1.2  2000/06/24 20:20:33  gerd
 112  *      Added the toploop printer.
 113  *
 114  * Revision 1.1  2000/04/15 13:07:48  gerd
 115  *      Initial revision.
 116  *
 117  *
 118  *)