Module Iovec
The iovec module provides lightweight views over Bigarrays, and gives access to POSIX vectored I/O system calls.
type buffer
The backing data for an Iovec. Data is stored outside of the OCaml heap, its contents are not moved or scanned by the garbage collector, and it can be passed as-is to system calls or C functions functions without copying.
type view
= private
{
buf : buffer;
backing data
off : int;
start of this view
len : int;
number of bytes in this view
}
A lightweight view over a heavyweight buffer. A new view may be derived from an existing view only by narrowing it with
seek
ortrunc
.
I/O vectors
type t
= view list
The central data structure of this module. The functions in this module treat the spans covered by the views in a list as a single, contiguous sequence of bytes, with the head of the list covering the start of the sequence, and the tail covering the end.
val of_bigarray : (char, Stdlib.Bigarray.int8_unsigned_elt, Stdlib.Bigarray.c_layout) Stdlib.Bigarray.Array1.t -> t
of_bigarray
constructs an iovec over an existing bigarray, covering the full length of the bigarray. The contents of the bigarray are not modified.
val create : int -> t
create size
allocates a freshbuffer
ofsize
bytes and creates a view over it. The contents of the buffer are initialized to 0.
val length : t -> int
length
is the total length of all views in the iovec.
exception
OOB
The
OOB
exception is raised if one of the arguments toseek
,trunc
,get
, orset
are outside the boundaries of a view.
val get : t -> int -> char
get iov i
fetches the byte at the given index in the view. It is equivalent to iov.%{i}
val set : t -> int -> char -> unit
set iov i v
sets the byte at the given index in the view. It is equivalent to iov.%{i} <- v
val set_int8 : t -> int -> int -> unit
val set_int16 : t -> int -> int -> unit
val set_int32 : t -> int -> int -> unit
val set_int64 : t -> int -> int -> unit
val fold_lefti : f:('a -> int -> t -> 'a) -> init:'a -> t -> 'a
fold_lefti ~f ~init iov
is equal tof (... (f (f init i1 iov) i2 iov) ...) ((length iov)-1) iov
where
f
receives the indices of iov rather than the values at those indices.
val str_equal : t -> string -> bool
str_equal iov s
is true if the characters iniov
are equal to the characters ins
.
val str_prefix : t -> string -> bool
has_prefix iov s
is true if the contents ofiov
start withs
.
val to_int : t -> int
to_int iov i n
decodes all bytes iniov
as an unsigned, little-endian integer. bits higher thanSys
.int_size are ignored.
val to_int64 : t -> int64
to_int64 iov
is liketo_int
, but allocates anint64
to store the result.
val to_string : t -> string
to_string iov
is a newly allocated string with the current contents ofiov
.
val copy : src:t -> dst:t -> int
copy ~src ~dst
copies data fromsrc
todst
, returning the number of bytes written todst
, which will be the lesserlength src
andlength dst
val memset : t -> char -> unit
memset iov c
sets all bytes iniov
toc
.
val hexdump : ?max:int -> t -> string
hexdump iov
is a string where each byte of the iovec is printed as "%02x ".
System calls
val readv : Unix.file_descr -> t -> int
readv fd iov
uses the readv(2) system call to read data from a file descriptor into an I/O vector, returning the number of bytes read, which will be less than or equal tolen iov
val preadv : Unix.file_descr -> t -> off:int -> int
preadv is like
readv
, but allows the caller to read from a specific region of the file by specifying an offset to start reading from. The file descriptor's internal position in the file is not changed.preadv
andpwritev
are not valid to use on a file descriptor that does not support seeking, such as a pipe or socket.
val writev : Unix.file_descr -> t -> int
writev uses the writev(2) system call to write data to a file descriptor from an I/O vector.
writev
returns the number of bytes written.
val pwritev : Unix.file_descr -> t -> off:int -> int
pwritev is like
writev
, but allows the caller to write to a specific region of the file by specifying an offset to start writing to.
Ring buffers
val ring_create : int -> ring
ring_create n
is a ring capable of holding at leastn
bytes. The initial contents of the ring are initialized to 0.
val ring_cap : ring -> int
ring_cap r
is the maximum capacity of the ring.
val ring_vacant : ring -> t
ring_vacant r
is an I/O vector covering the vacant space in the ring, starting at the end of the occupied space.
val ring_drop : ring -> int -> unit
ring_drop r n
dropsn
bytes from the start of the occupied space.
val ring_grow : ring -> int -> unit
ring_extend r n
increases the ring's occupied space byn
bytes.
Encoding data
type writer
A
writer
keeps track of data written to an I/O vector and allows for the easy creation of length-prefixed fields.
val writer : hdr:int -> init:int -> t -> writer
writer ~hdr ~init iov
is a writer that reserveshdr
bytes of space for the size header and writes to the remainder ofiov
. The final size written will be the sum ofinit
and the total number of bytes written before a call to one of theresult
functions.
val nested : hdr:int -> writer -> writer
nested ~hdr w
creates a writer from the current position ofw
. It can be used to nest length-prefixed fields within length-prefixed fields. If a non-zero header width is specified, its initial value is 0.
val advance : w:writer -> int -> writer
advance ~w n
advances the writer byn
bytes. It does not write to the underlying vector.
val put_uint8 : w:writer -> int -> writer
val put_uint16 : w:writer -> int -> writer
val put_uint32 : w:writer -> int -> writer
val put_uint64 : w:writer -> int -> writer