Previous  Up  Next

Module Iobuf

module Iobuf: sig .. end
A non-moving (in the gc sense) contiguous range of bytes, useful for I/O operations.

An iobuf consists of:

All iobuf operations are restricted to operate within the limits. Initially, the window of an iobuf is identical to the limits. A phantom type, "seek" permission, controls whether or not code is allowed to change the limits and window. With seek permission, the limits can be narrowed, but can never be widened, and the window can be set to an arbitrary subrange of the limits.

A phantom type controls whether code can read and write bytes in the bigstring (within the limits) or can only read them.

To present a restricted view of an iobuf to a client, one can create a sub-iobuf or add a type constraint.

type no_seek
no_seek and seek are defined and used in a similar manner to read_only and read_write.

like read_only

type seek = private no_seek
like read_write
type (+'data_perm_read_write, +'seek_permission) t 
include Invariant.S2

Creation


val create : len:int -> ('a, 'b) t
create ~len creates a new iobuf, backed by a bigstring of length len, with the limits and window set to the entire bigstring.
val of_bigstring : ?pos:int -> ?len:int -> Bigstring.t -> ('a, 'b) t
of_bigstring bigstring ~pos ~len returns an iobuf backed by bigstring, with the window and limits specified starting at pos and of length len.
val of_string : string -> ('a, 'b) t
of_string s returns a new iobuf whose contents are s.
val sub : ?pos:int -> ?len:int -> ('d, 'a) t -> ('d, 'b) t
sub t ~pos ~len returns a new iobuf with limits and window set to the subrange of t specified by pos and len. sub preserves data permissions, but allows arbitrary seek permissions on the resulting iobuf.

Accessors


val capacity : ('a, 'b) t -> int
capacity t returns the size of t's limits subrange. The capacity of an iobuf can be reduced via narrow.
val length : ('a, 'b) t -> int
length t returns the size of t's window.
val is_empty : ('a, 'b) t -> bool
is_empty t is length t = 0.

Changing the limits


val narrow : ('a, seek) t -> unit
narrow t sets t's limits to the current window.

Changing the window


module Snapshot: sig .. end  with type ('d, 'w) iobuf := ('d, 'w) t
One can call snapshot t to get a snapshot of the front of the window, and then later restore that snapshot. 
val snapshot : ('a, seek) t -> Snapshot.t
val advance : ('a, seek) t -> int -> unit
advance t amount advances the front of the window by amount. It is an error to advance past the back of the window or the lower limit.
val resize : ('a, seek) t -> len:int -> unit
resize t sets the length of t's window, provided it does not exceed limits.
val rewind : ('a, seek) t -> unit
rewind t sets the front of the window to the lower limit.
val reset : ('a, seek) t -> unit
reset t sets the window to the limits.
val flip : ('a, seek) t -> unit
flip t sets the window to range from the lower limit to the front of the old window. This is typically called after a series of Fills, to reposition the window in preparation to Consume the newly written data.
val compact : (Common.read_write, seek) t -> unit
compact t copies data from the window to the lower limit of the iobuf and sets the window to range from the end of the copied data to the upper limit. This is typically called after a series of Consumes to save unread data and prepare for the next series of Fills and flip.

Getting and setting data



"consume" and "fill" functions access data at the front of the window and advance the front of the window. "peek" and "poke" functions access data but do not advance the window.
val to_string : ?len:int -> ('a, 'b) t -> string
to_string t returns the bytes in t as a string. It does not alter the window.
val consume_into_string : ?pos:int -> ?len:int -> ('a, seek) t -> string -> unit
consume_into_string t s ~pos ~len reads len bytes from t, advancing t's window accordingly, and writes them into s starting at pos. By default pos = 0 and len = String.length s - pos. It is an error if pos and len don't specify a valid region of s or len > length t.
val consume_into_bigstring : ?pos:int -> ?len:int -> ('a, seek) t -> Bigstring.t -> unit
module Consume: Accessors  with type ('a, 'd, 'w) t = ('d, seek) t -> 'a
Consume.string t ~len reads len characters (all, by default) from t into a new string and advances the front of the window accordingly. 
module Fill: Accessors  with type ('a, 'd, 'w) t = (read_write, seek) t -> 'a -> unit
Peek and Poke functions access a value at pos from the front of the window and do not advance. 
module Peek: Accessors  with type ('a, 'd, 'w) t = ('d, 'w) t -> pos:int -> 'a
module Poke: Accessors  with type ('a, 'd, 'w) t = (read_write, 'w) t -> pos:int -> 'a -> unit
module Unsafe: sig .. end
Unsafe has submodules that are like their corresponding module, except with no range checks. 
val fill_bin_prot : (Common.read_write, seek) t ->
       'a Bin_prot.Type_class.writer -> 'a -> unit Or_error.t
fill_bin_prot writes a bin-prot value to the front of the window, prefixed by its length, and advances the front of the window by the amount written. fill_bin_prot returns an error if the window is too small to write the value.

consume_bin_prot t reader reads a bin-prot value from the front of the window, which should have been written using fill_bin_prot, and advances the window by the amount read. consume_bin_prot returns an error if there is not a complete message in the window and in that case the window is left unchanged.

val consume_bin_prot : ('b, seek) t -> 'a Bin_prot.Type_class.reader -> 'a Or_error.t
val transfer : ?len:int ->
       src:('a, seek) t ->
       dst:(Common.read_write, seek) t -> unit
transfer blits len bytes from the front of src to the front of dst, advancing both. It is an error if len > length src || len > length dst || phys_equal src dst.
val memmove : (Common.read_write, 'a) t ->
       src_pos:int -> dst_pos:int -> len:int -> unit
memmove blits len bytes from src_pos to dst_pos in an iobuf, both relative to the front of the window. The window is not advanced.

I/O


val read_assume_fd_is_nonblocking : (Common.read_write, seek) t ->
       Iobuf_intf.Unix.File_descr.t -> int
Iobuf has analogs of various Bigstring functions. These analogs advance by the amount written/read.
val pread_assume_fd_is_nonblocking : (Common.read_write, seek) t ->
       Iobuf_intf.Unix.File_descr.t -> offset:int -> int
val recvfrom_assume_fd_is_nonblocking : (Common.read_write, seek) t ->
       Iobuf_intf.Unix.File_descr.t -> int * Iobuf_intf.Unix.sockaddr
val recvmmsg_assume_fd_is_nonblocking : (Iobuf_intf.Unix.File_descr.t ->
        ?count:int ->
        ?srcs:Iobuf_intf.Unix.sockaddr array ->
        (Common.read_write, seek) t array -> int)
       Or_error.t
val send_nonblocking_no_sigpipe : unit ->
       (('a, seek) t -> Iobuf_intf.Unix.File_descr.t -> int option)
       Or_error.t
val sendto_nonblocking_no_sigpipe : unit ->
       (('a, seek) t ->
        Iobuf_intf.Unix.File_descr.t -> Iobuf_intf.Unix.sockaddr -> int option)
       Or_error.t
val write_assume_fd_is_nonblocking : ('a, seek) t -> Iobuf_intf.Unix.File_descr.t -> int
val pwrite_assume_fd_is_nonblocking : ('a, seek) t -> Iobuf_intf.Unix.File_descr.t -> offset:int -> int
val sexp_of_no_seek : no_seek -> Sexplib.Sexp.t
like read_only
val sexp_of_seek : seek -> Sexplib.Sexp.t
like read_write
val sexp_of_t : ('data_perm_read_write -> Sexplib.Sexp.t) ->
       ('seek_permission -> Sexplib.Sexp.t) ->
       ('data_perm_read_write, 'seek_permission) t -> Sexplib.Sexp.t
The first type parameter controls whether the iobuf can be written to. The second type parameter controls whether the window and limits can be changed.

To allow read_write or read_only access, a function's type uses _ rather than read_only as the type argument to t. Analogously, to allow no_seek or seek access, a function's type uses _ rather than no_seek as the type argument to t. Using _ allows the function to be directly applied to either permission. Using a specific permission would require code to use coercion :>.


Creation



create ~len creates a new iobuf, backed by a bigstring of length len, with the limits and window set to the entire bigstring.

of_bigstring bigstring ~pos ~len returns an iobuf backed by bigstring, with the window and limits specified starting at pos and of length len.

default is 0

default is Bigstring.length bigstring - pos

of_string s returns a new iobuf whose contents are s.

sub t ~pos ~len returns a new iobuf with limits and window set to the subrange of t specified by pos and len. sub preserves data permissions, but allows arbitrary seek permissions on the resulting iobuf.

Accessors



capacity t returns the size of t's limits subrange. The capacity of an iobuf can be reduced via narrow.

length t returns the size of t's window.

is_empty t is length t = 0.

Changing the limits



narrow t sets t's limits to the current window.

Changing the window



One can call snapshot t to get a snapshot of the front of the window, and then later restore that snapshot. This is useful for speculatively parsing, and then rewinding when there isn't enough data to finish.

Using a snapshot with a different iobuf, even a sub iobuf of the snapshotted one, has unspecified results. An exception may be raised, or a silent error may occur. However, the safety guarantees of the iobuf will not be violated, i.e., the attempt will not enlarge the limits of the subject iobuf.

advance t amount advances the front of the window by amount. It is an error to advance past the back of the window or the lower limit.

resize t sets the length of t's window, provided it does not exceed limits.

rewind t sets the front of the window to the lower limit.

reset t sets the window to the limits.

flip t sets the window to range from the lower limit to the front of the old window. This is typically called after a series of Fills, to reposition the window in preparation to Consume the newly written data.

compact t copies data from the window to the lower limit of the iobuf and sets the window to range from the end of the copied data to the upper limit. This is typically called after a series of Consumes to save unread data and prepare for the next series of Fills and flip.

Getting and setting data



"consume" and "fill" functions access data at the front of the window and advance the front of the window. "peek" and "poke" functions access data but do not advance the window.

to_string t returns the bytes in t as a string. It does not alter the window.

consume_into_string t s ~pos ~len reads len bytes from t, advancing t's window accordingly, and writes them into s starting at pos. By default pos = 0 and len = String.length s - pos. It is an error if pos and len don't specify a valid region of s or len > length t.

Consume.string t ~len reads len characters (all, by default) from t into a new string and advances the front of the window accordingly.

Peek and Poke functions access a value at pos from the front of the window and do not advance.

Unsafe has submodules that are like their corresponding module, except with no range checks. Hence, mistaken uses can cause segfaults. Be careful!

fill_bin_prot writes a bin-prot value to the front of the window, prefixed by its length, and advances the front of the window by the amount written. fill_bin_prot returns an error if the window is too small to write the value.

consume_bin_prot t reader reads a bin-prot value from the front of the window, which should have been written using fill_bin_prot, and advances the window by the amount read. consume_bin_prot returns an error if there is not a complete message in the window and in that case the window is left unchanged.

transfer blits len bytes from the front of src to the front of dst, advancing both. It is an error if len > length src || len > length dst || phys_equal src dst.

default is min (length src) (length dst)

memmove blits len bytes from src_pos to dst_pos in an iobuf, both relative to the front of the window. The window is not advanced.

I/O



Iobuf has analogs of various Bigstring functions. These analogs advance by the amount written/read.