package core

  1. Overview
  2. Docs
package core
Legend:
Library
Module
Module type
Parameter
Class
Class type

Make builds a module that is like Iobuf, except that the module also has some controls for whether the various Iobuf functions do invariant checking and/or show debug messages. Initially, the bool ref's are true.

The performance of the functions in the module resulting from Make can be much worse than that of a plain Iobuf, even with all the controls set to false.

Parameters

Signature

We use module type of struct include Iobuf end rather than module type of Iobuf so that the debugging functions work on normal Iobufs.

include module type of struct include Iobuf end
type nonrec seek = Iobuf_intf.seek
include sig ... end
val sexp_of_seek : seek -> Ppx_sexp_conv_lib.Sexp.t
type nonrec no_seek = Iobuf_intf.no_seek
include sig ... end
val sexp_of_no_seek : no_seek -> Ppx_sexp_conv_lib.Sexp.t
type (-'data_perm_read_write, +'seek_permission) t = ('data_perm_read_write, 'seek_permission) Iobuf.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.

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.

val invariant : 'a Base__.Invariant_intf.inv -> 'b Base__.Invariant_intf.inv -> ('a, 'b) t Base__.Invariant_intf.inv
module Window = Iobuf.Window

Provides a Window.Hexdump submodule that renders the contents of t's window.

module Limits = Iobuf.Limits

Provides a Window.Hexdump submodule that renders the contents of t's limits.

Provides a Hexdump submodule that renders the contents of t's window and limits using indices relative to the limits.

include Iobuf_intf.Compound_hexdump with type ('rw, 'seek) t := ('rw, 'seek) t
module Hexdump = Iobuf.Hexdump
module Debug = Iobuf.Debug

Provides a Debug.Hexdump submodule that renders the contents of t's window, limits, and underlying bigstring using indices relative to the bigstring.

Creation

val create : len:int -> (_, _) 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 -> Core_kernel.Bigstring.t -> ([< Core_kernel.Perms.Read_write.t ], _) 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.

forbid immutable to prevent aliasing

val of_string : string -> (_, _) t

of_string s returns a new iobuf whose contents are s.

val sub_shared : ?pos:int -> ?len:int -> ('d, _) t -> ('d, _) t

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.

val set_bounds_and_buffer : src:([> Core_kernel.Perms.Write.t ] as 'data, _) t -> dst:('data, seek) t -> unit

set_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_kernel.Perms.Write.t ] as 'data, _) t -> dst:('data, seek) t -> unit

set_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.

val read_only : ([> Core_kernel.Perms.Read.t ], 's) t -> (Core_kernel.Perms.Read.t, 's) t

Generalization

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 no_seek : ('r, _) t -> ('r, no_seek) t

Accessors

val capacity : (_, _) t -> int

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

val length : (_, _) t -> int

length t returns the size of t's window.

val is_empty : (_, _) t -> bool

is_empty t is length t = 0.

Changing the limits

val narrow : (_, seek) t -> unit

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

val narrow_lo : (_, seek) t -> unit

narrow_lo t sets t's lower limit to the beginning of the current window.

val narrow_hi : (_, seek) t -> unit

narrow_hi t sets t's upper limit to the end of the current window.

Changing the window

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 = Iobuf.Bound
module Lo_bound = Iobuf.Lo_bound
module Hi_bound = Iobuf.Hi_bound
val advance : (_, seek) t -> int -> unit

advance 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.

val unsafe_advance : (_, seek) t -> int -> unit

unsafe_advance is like advance but with no bounds checking, so incorrect usage can easily cause segfaults.

val resize : (_, seek) t -> len:int -> unit

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

val unsafe_resize : (_, seek) t -> len:int -> unit

unsafe_resize is like resize but with no bounds checking, so incorrect usage can easily cause segfaults.

val rewind : (_, seek) t -> unit

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

val reset : (_, seek) t -> unit

reset t sets the window to the limits.

val flip_lo : (_, seek) t -> unit

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 -> Lo_bound.t -> unit
val compact : (Core_kernel.Perms.Read_write.t, 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_lo.

val bounded_compact : (Core_kernel.Perms.Read_write.t, seek) t -> Lo_bound.t -> Hi_bound.t -> unit
val flip_hi : (_, seek) t -> unit

flip_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 buf;

Now the window of buf ranges over the remainder of the data.

val bounded_flip_hi : (_, seek) t -> Hi_bound.t -> unit
val protect_window_and_bounds : ('rw, no_seek) t -> f:(('rw, seek) t -> 'a) -> 'a

protect_window_and_bounds t ~f applies f to t and restores t's bounds and buffer afterward.

Getting and setting data

"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.

val to_string : ?len:int -> ([> Core_kernel.Perms.Read.t ], _) t -> string

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 -> string

Equivalent to Hexdump.to_string_hum. Renders t's windows and limits.

module Consume = Iobuf.Consume

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

module Fill = Iobuf.Fill

Fill.bin_prot X.bin_write_t t x writes x to t in bin-prot form, advancing past the bytes written.

module Peek = Iobuf.Peek

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

module Poke = Iobuf.Poke

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 = Iobuf.Unsafe

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

val bin_prot_length_prefix_bytes : int

The number of bytes in the length prefix of consume_bin_prot and fill_bin_prot.

val fill_bin_prot : ([> Core_kernel.Perms.Write.t ], seek) t -> 'a Core__.Import.Bin_prot.Type_class.writer -> 'a -> unit Core_kernel.Or_error.t

fill_bin_prot writes a bin-prot value to the lower bound of the window, prefixed by its length, and advances 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 lower bound 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.

Don't use these without a good reason, as they are incompatible with similar functions in Reader and Writer. They use a 4-byte length rather than an 8-byte length.

val consume_bin_prot : ([> Core_kernel.Perms.Read.t ], seek) t -> 'a Core__.Import.Bin_prot.Type_class.reader -> 'a Core_kernel.Or_error.t
module Blit = Iobuf.Blit

Blit copies between iobufs and advances neither src nor dst.

module Blit_consume = Iobuf.Blit_consume

Blit_consume copies between iobufs and advances src but does not advance dst.

module Blit_fill = Iobuf.Blit_fill

Blit_fill copies between iobufs and advances dst but does not advance src.

module Blit_consume_and_fill = Iobuf.Blit_consume_and_fill

Blit_consume_and_fill copies between iobufs and advances both src and dst.

I/O

type ok_or_eof = Iobuf.ok_or_eof =
  1. | Ok
  2. | Eof
include sig ... end
val compare_ok_or_eof : ok_or_eof -> ok_or_eof -> int
val sexp_of_ok_or_eof : ok_or_eof -> Ppx_sexp_conv_lib.Sexp.t
val input : ([> Core_kernel.Perms.Write.t ], seek) t -> Core__.Import.In_channel.t -> ok_or_eof

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

val read_assume_fd_is_nonblocking : ([> Core_kernel.Perms.Write.t ], seek) t -> Iobuf_intf.Unix.File_descr.t -> int
val pread_assume_fd_is_nonblocking : ([> Core_kernel.Perms.Write.t ], seek) t -> Iobuf_intf.Unix.File_descr.t -> offset:int -> unit
val recvfrom_assume_fd_is_nonblocking : ([> Core_kernel.Perms.Write.t ], seek) t -> Iobuf_intf.Unix.File_descr.t -> Iobuf_intf.Unix.sockaddr
module Recvmmsg_context = Iobuf.Recvmmsg_context

recvmmsg's context comprises data needed by the system call. Setup can be expensive, particularly for many buffers.

recvmmsg_assume_fd_is_nonblocking fd context returns the number of context iobufs read into (or errno). fd must not block. THREAD_IO_CUTOFF is ignored.

EINVAL is returned if an Iobuf passed to Recvmmsg_context.create has its buf or limits changed.

val output : ([> Core_kernel.Perms.Read.t ], seek) t -> Core__.Import.Out_channel.t -> unit
val write_assume_fd_is_nonblocking : ([> Core_kernel.Perms.Read.t ], seek) t -> Iobuf_intf.Unix.File_descr.t -> unit
val pwrite_assume_fd_is_nonblocking : ([> Core_kernel.Perms.Read.t ], seek) t -> Iobuf_intf.Unix.File_descr.t -> offset:int -> unit

Expert

module Expert = Iobuf.Expert

The Expert module is for building efficient out-of-module Iobuf abstractions.

val check_invariant : bool Stdlib.Pervasives.ref
val show_messages : bool Stdlib.Pervasives.ref
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct