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 or trunc.

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 pp : Stdlib.Format.formatter -> t -> unit
val empty : t

The empty I/O vector. Contains nothing.

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 fresh buffer of size 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 to seek, trunc, get, or set are outside the boundaries of a view.

val seek : t -> int -> t

seek iov n skips the next n bytes in the vector.

val trunc : t -> int -> t

trunc iov n truncates the vector to n bytes.

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 to

f (... (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 in iov are equal to the characters in s.

val str_prefix : t -> string -> bool

has_prefix iov s is true if the contents of iov start with s.

val to_int : t -> int

to_int iov i n decodes all bytes in iov as an unsigned, little-endian integer. bits higher than Sys.int_size are ignored.

val to_int64 : t -> int64

to_int64 iov is like to_int, but allocates an int64 to store the result.

val to_string : t -> string

to_string iov is a newly allocated string with the current contents of iov.

val copy : src:t -> dst:t -> int

copy ~src ~dst copies data from src to dst, returning the number of bytes written to dst, which will be the lesser length src and length dst

val memset : t -> char -> unit

memset iov c sets all bytes in iov to c.

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 to len 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 and pwritev 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.

val blksize : Unix.file_descr -> int

blksize fd retrieves the I/O block size of the file referenced by fd. It may be beneficial to size buffers as some multiple of the block size.

Ring buffers

type ring

A ring is a fixed-size, FIFO queue for bytes which provides efficient re-use of memory.

val ring_create : int -> ring

ring_create n is a ring capable of holding at least n 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_occupied : ring -> t

ring_occupied r is an I/O vector covering the occupied space in r.

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 drops n bytes from the start of the occupied space.

val ring_grow : ring -> int -> unit

ring_extend r n increases the ring's occupied space by n 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 reserves hdr bytes of space for the size header and writes to the remainder of iov. The final size written will be the sum of init and the total number of bytes written before a call to one of the result functions.

val nested : hdr:int -> writer -> writer

nested ~hdr w creates a writer from the current position of w. 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 by n 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
val put_string : w:writer -> string -> writer

put_string ~w s writes the 16-bit length of s to w, followed by the content of of the string s.

val result : writer -> t
val result_rest : writer -> t
val result_both : writer -> t * t
val result_n : writer -> int