IobufA 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 its limits. A phantom type, the "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.
Functions operate on the window unless the documentation or naming indicates otherwise.
module type Basic = sig ... endmodule type Bin_io = sig ... endmodule type Blit = sig ... endmodule type Blit_consume = sig ... endmodule type Blit_fill = sig ... endmodule type Blit_consume_and_fill = sig ... endmodule type Expert = sig ... endmodule type Hexdump_all = sig ... endmodule type Itoa = sig ... endmodule type Date_string = sig ... endmodule type Accessors_common = sig ... endCollections of access functions. These abstract over Iobuf.Consume, Iobuf.Fill, Iobuf.Peek, and Iobuf.Poke.
module type Accessors_read = sig ... end('d, 'w, 'l) Iobuf.t accessor function manipulating 'a, either writing it to the iobuf or reading it from the iobuf.
module type Accessors_write = sig ... end('d, 'w, 'l) Iobuf.t accessor function manipulating 'a, either writing it to the iobuf or reading it from the iobuf.
The src_pos argument of Core.Blit.blit doesn't make sense here.
module type Consuming_blit = sig ... endmodule type Consume_safe = sig ... endmodule type Fill_safe = sig ... endmodule type Peek_common = sig ... endmodule type Peek_safe = sig ... endmodule type Poke_safe = sig ... endmodule type Consume_unsafe = sig ... endmodule type Fill_unsafe = sig ... endmodule type Peek_unsafe = sig ... endmodule type Poke_unsafe = sig ... endmodule Repr : sig ... endtype (-'data_perm_read_write, +'seek_permission, 'buffer_locality) t =
private 'buffer_locality Repr.tThe first type parameter controls whether the iobuf can be written to. The second type parameter controls whether the window and limits can be changed. The third type parameter controls whether the Bigstring.t buffer must be global or not.
See the Perms module for information on how the first type parameter is used.
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 :>.
There is no t_of_sexp. One should use Iobuf.Hexdump.t_of_sexp or @sexp.opaque as desired.
include Basic with type ('rw, 'seek, 'loc) t := ('rw, 'seek, 'loc) tval sexp_of_seek : seek -> Sexplib0.Sexp.tval sexp_of_no_seek : no_seek -> Sexplib0.Sexp.ttype nonrec global = Core.Modes.At_locality.globalval sexp_of_global : global -> Sexplib0.Sexp.ttype nonrec local = Core.Modes.At_locality.localval sexp_of_local : local -> Sexplib0.Sexp.tGlobalize as if t had zero type parameters. Works because the parameters are phantom types, and do not represent actual values that need to be globalized.
module With_shallow_sexp : sig ... endval invariant : (_, _, _) t -> unitval create : len:int -> (_, _, _) tcreate ~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 @ local ->
(?len:int @ local ->
(Core.Bigstring.t ->
([< Core.read_write ], _, _) t) @ local) @ localof_bigstring bigstring ~pos ~len returns an iobuf backed by bigstring, with the window and limits specified starting at pos and of length len.
forbid immutable to prevent aliasing
val of_bigstring_sub :
pos:int ->
len:int ->
Core.Bigstring.t ->
([< Core.read_write ], _, _) tMore efficient than the above (optional arguments are costly).
val unsafe_of_bigstring_sub :
pos:int ->
len:int ->
Core.Bigstring.t ->
([< Core.read_write ], _, _) tYet more efficient than the above, by skipping bounds checks.
val of_string : string @ local -> (_, _, _) tof_string s returns a new iobuf whose contents are s. The stack-allocating version still performs global allocation of the backing buffer.
sub_shared t ~pos ~len returns a new iobuf with limits and window set to the subrange of t's window specified by pos and len. sub_shared preserves data permissions, but allows arbitrary seek permissions on the resulting iobuf.
sub_shared__local is like sub_shared, but it allocates the iobuf record locally.
More efficient than the above (optional arguments are costly).
copy t returns a new iobuf whose contents are the same as those in the window of t.
clone t returns a new iobuf that is a deep-copy of t including an exact copy of the underlying buffer and bounds. This means data outside the window is copied as well.
val transfer :
src:([> Core.read ], _, _) t @ local ->
(dst:([> Core.write ], seek, _) t @ local ->
unit) @ localtransfer ~src ~dst makes the window of dst into a copy of the window of src. Like blito, transfer will raise if Iobuf.length dst < Iobuf.length src.
It is a utility function defined as reset dst; blito ~src ~dst; flip_lo dst.
val set_bounds_and_buffer :
src:([> Core.write ] as 'data, _, global) t @ local ->
(dst:('data, seek, _) t @ local ->
unit) @ localset_bounds_and_buffer ~src ~dst copies bounds metadata (i.e., limits and window) and shallowly copies the buffer (data pointer) from src to dst. It does not access data, but does allow access through dst. This makes dst an alias of src.
Because set_bounds_and_buffer creates an alias, we disallow immutable src and dst using [> write]. Otherwise, one of src or dst could be read_write :> read and the other immutable :> read, which would allow you to write the immutable alias's data through the read_write alias.
set_bounds_and_buffer is typically used with a frame iobuf that need only be allocated once. This frame can be updated repeatedly and handed to users, without further allocation. Allocation-sensitive applications need this.
val set_bounds_and_buffer_sub :
pos:int ->
len:int ->
src:([> Core.write ] as 'data, _, global) t @ local ->
(dst:('data, seek, _) t @ local ->
unit) @ localset_bounds_and_buffer_sub ~pos ~len ~src ~dst is a more efficient version of set_bounds_and_buffer ~src:(Iobuf.sub_shared ~pos ~len src) ~dst.
set_bounds_and_buffer ~src ~dst is not the same as set_bounds_and_buffer_sub ~dst ~src ~len:(Iobuf.length src) because the limits are narrowed in the latter case.
~len and ~pos are mandatory for performance reasons, in concert with @@inline. If they were optional, allocation would be necessary when passing a non-default, non-constant value, which is an important use case.
One may wonder why you'd want to call no_seek, given that a cast is already possible, e.g., t : (_, seek, _) t :> (_, no_seek, _) t. It turns out that if you want to define some f : (_, _, _) t -> unit of your own that can be conveniently applied to seek iobufs without the user having to cast seek up, you need this no_seek function.
read_only is more of a historical convenience now that read_write is a polymorphic variant, as one can now explicitly specify the general type for an argument with something like t : (_ perms, _) t :> (read, _) t.
val capacity : (_, _, _) t @ local -> intcapacity t returns the size of t's limits subrange. The capacity of an iobuf can be reduced via narrow.
val length : (_, _, _) t @ local -> intlength t returns the size of t's window.
val length_lo : (_, _, _) t @ local -> intlength_lo t returns the length that t's window would have after calling flip_lo, without actually changing the window. This is the number of bytes between the lower limit and the start of the window.
When you're writing to the window, you can think of this as the number of bytes already written. When reading from the window, this can mean the number of bytes already consumed.
This is equivalent to:
Iobuf.Expert.(lo t - lo_min t).
val length_hi : (_, _, _) t @ local -> intlength_hi t returns the length that t's window would have after calling flip_hi, without actually changing the window. This is the number of bytes between the end of the window and the upper limit of the buffer.
This is equivalent to:
Iobuf.Expert.(hi_max t - hi t).
val is_empty : (_, _, _) t @ local -> boolis_empty t is length t = 0.
narrow_lo t sets t's lower limit to the beginning of the current window.
narrow_hi t sets t's upper limit to the end of the current window.
memcmp a b first compares the length of a and b's windows and then compares the bytes in the windows for equivalence.
One can call Lo_bound.window t to get a snapshot of the lower bound of the window, and then later restore that snapshot with Lo_bound.restore. This is useful for speculatively parsing, and then rewinding when there isn't enough data to finish.
Similarly for Hi_bound.window and Lo_bound.restore.
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.
module type Bound = sig ... endadvance t amount advances the lower bound of the window by amount. It is an error to advance past the upper bound of the window or the lower limit.
unsafe_advance is like advance but with no bounds checking, so incorrect usage can easily cause segfaults.
resize t sets the length of t's window, provided it does not exceed limits.
unsafe_resize is like resize but with no bounds checking, so incorrect usage can easily cause segfaults.
rewind t sets the lower bound of the window to the lower limit.
flip_lo t sets the window to range from the lower limit to the lower bound 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.
The bounded version narrows the effective limit. This can preserve some data near the limit, such as a hypothetical packet header (in the case of bounded_flip_lo) or unfilled suffix of a buffer (in bounded_flip_hi).
val bounded_flip_lo : (_, seek, _) t @ local -> (Lo_bound.t -> unit) @ localval compact : (Core.read_write, seek, _) t @ local -> unitcompact 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_lo.
val bounded_compact :
(Core.read_write, seek, _) t @ local ->
(Lo_bound.t ->
(Hi_bound.t ->
unit) @ local) @ localflip_hi t sets the window to range from the the upper bound of the current window to the upper limit. This operation is dual to flip_lo and is typically called when the data in the current (narrowed) window has been processed and the window needs to be positioned over the remaining data in the buffer. For example:
(* ... determine initial_data_len ... *)
Iobuf.resize buf ~len:initial_data_len;
(* ... and process initial data ... *)
Iobuf.flip_hi bufNow the window of buf ranges over the remainder of the data.
val bounded_flip_hi : (_, seek, _) t @ local -> (Hi_bound.t -> unit) @ localval protect_window_bounds_and_buffer :
('rw, no_seek, global) t ->
f:(('rw, seek, global) t -> 'a) @ local ->
'aprotect_window_bounds_and_buffer t ~f calls f t with t's bounds set to its current window, and restores t's window, bounds, and buffer afterward.
val protect_window_bounds_and_buffer__local :
('rw, no_seek, global) t ->
f:(('rw, seek, global) t -> 'a @ local) @ local ->
'a @ localprotect_window_bounds_and_buffer__local is similar to protect_window_bounds_and_buffer except that it returns a local value
val protect_window_bounds_and_buffer_1 :
('rw, no_seek, global) t ->
'a ->
f:(('rw, seek, global) t -> ('a -> 'b) @ local) @ local ->
'bprotect_window_bounds_and_buffer_1 t x ~f is a more efficient version of protect_window_bounds_and_buffer t ~f:(fun t -> f t x).
val protect_window_bounds_and_buffer_2 :
('rw, no_seek, global) t ->
'a ->
'b ->
f:(('rw, seek, global) t -> ('a -> ('b -> 'c) @ local) @ local) @ local ->
'cprotect_window_bounds_and_buffer_2 t x y ~f is a more efficient version of protect_window_bounds_and_buffer t ~f:(fun t -> f t x y).
val protect_window_bounds_and_buffer_3 :
('rw, no_seek, global) t ->
'a ->
'b ->
'c ->
f:
(('rw, seek, global) t ->
('a ->
('b ->
('c ->
'd) @ local) @ local) @ local) @ local ->
'dprotect_window_bounds_and_buffer_3 t x y z ~f is a more efficient version of protect_window_bounds_and_buffer t ~f:(fun t -> f t x y z).
"consume" and "fill" functions access data at the lower bound of the window and advance the lower bound 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.
val to_string_hum : ?max_lines:int -> (_, _, _) t @ local -> stringEquivalent to Hexdump.to_string_hum. Renders t's windows and limits.
val to_bytes : ?len:int -> (_, _, _) t @ local -> Core.Bytes.tto_bytes t returns the bytes in t as a bytes. It does not alter the window.
val of_bytes : Core.Bytes.t -> (_, _, _) tof_bytes b returns a new iobuf whose contents is b.
val memset :
(Core.read_write, _, _) t @ local ->
(pos:int ->
(len:int ->
(char ->
unit) @ local) @ local) @ localmemset t ~pos ~len c fills t with c within the range [pos, pos + len).
val unsafe_memset :
(Core.read_write, _, _) t @ local ->
(pos:int ->
(len:int ->
(char ->
unit) @ local) @ local) @ localunsafe_memset t ~pos ~len c fills t with c within the range [pos, pos + len), without bounds checks.
val zero : (Core.read_write, _, _) t @ local -> unitmemsets a buffer to zero.
Create a new iobuf whose contents are the appended contents of the passed array.
val contains :
([> Core.read ], _, _) t ->
substring:Core.Bigstring.t @ local ->
boolmodule Window :
Core.Hexdump.S3 with type ('rw, 'seek, 'loc) t := ('rw, 'seek, 'loc) tProvides a Window.Hexdump submodule that renders the contents of t's window.
module Limits :
Core.Hexdump.S3 with type ('rw, 'seek, 'loc) t := ('rw, 'seek, 'loc) tProvides a Limits.Hexdump submodule that renders the contents of t's limits.
module Hexdump :
Hexdump_all with type ('rw, 'seek, 'loc) t = ('rw, 'seek, 'loc) tProvides a Hexdump submodule that renders the contents of t's window and limits using indices relative to the limits.
module Debug : sig ... endProvides a Debug.Hexdump submodule that renders the contents of t's window, limits, and underlying bigstring using indices relative to the bigstring.
Blit copies between iobufs and advances neither src nor dst.
module Blit_consume :
Blit_consume with type ('rw, 'seek, 'loc) t := ('rw, 'seek, 'loc) tBlit_consume copies between iobufs and advances src but does not advance dst.
Blit_fill copies between iobufs and advances dst but does not advance src.
module Blit_consume_and_fill :
Blit_consume_and_fill with type ('rw, 'seek, 'loc) t := ('rw, 'seek, 'loc) tBlit_consume_and_fill copies between iobufs and advances both src and dst.
module Date_string : Date_stringmodule Consume :
Consume_safe with type ('rw, 'seek, 'loc) iobuf := ('rw, 'seek, 'loc) tConsume.string t ~len reads len characters (all, by default) from t into a new string and advances the lower bound of the window accordingly.
Fill.bin_prot X.bin_write_t t x writes x to t in bin-prot form, advancing past the bytes written.
Peek and Poke functions access a value at pos from the lower bound of the window and do not advance.
Poke.bin_prot X.bin_write_t t x writes x to the beginning of t in binary form without advancing. You can use X.bin_size_t to tell how long it was. X.bin_write_t is only allowed to write that portion of the buffer you have access to.
module Unsafe : sig ... endUnsafe has submodules that are like their corresponding module, except with no range checks. Hence, mistaken uses can cause segfaults. Be careful!