eio_linux 0.6 · OCaml Package

Low-level API for using uring directly.

val noop : unit -> unit

noop () performs a uring noop. This is only useful for benchmarking.

Time functions

val sleep_until : float -> unit

sleep_until time blocks until the current time is time.

Fixed-buffer memory allocation functions

The size of the fixed buffer is set when calling run, which attempts to allocate a fixed buffer. However, that may fail due to resource limits.

val alloc_fixed : unit -> Uring.Region.chunk option

Allocate a chunk of memory from the fixed buffer.

Warning: The memory is NOT zeroed out.

Passing such memory to Linux can be faster than using normal memory, in certain cases. There is a limited amount of such memory, and this will return None if none is available at present.

val alloc_fixed_or_wait : unit -> Uring.Region.chunk

Like alloc_fixed, but if there are no chunks available then it waits until one is.

val free_fixed : Uring.Region.chunk -> unit

val with_chunk : fallback:(unit -> 'a) -> (Uring.Region.chunk -> 'a) -> 'a

with_chunk ~fallback fn runs fn chunk with a freshly allocated chunk and then frees it.

If no chunks are available, it runs fallback () instead.

File manipulation functions

val openfile : 
  sw:Eio.Std.Switch.t ->
  string ->
  Unix.open_flag list ->
  int ->
  FD.t

Like Unix.open_file.

val openat2 : 
  sw:Eio.Std.Switch.t ->
  ?seekable:bool ->
  access:[ `R | `W | `RW ] ->
  flags:Uring.Open_flags.t ->
  perm:Unix.file_perm ->
  resolve:Uring.Resolve.t ->
  ?dir:FD.t ->
  string ->
  FD.t

openat2 ~sw ~flags ~perm ~resolve ~dir path opens dir/path.

See Uring.openat2 for details.

val read_upto : 
  ?file_offset:Optint.Int63.t ->
  FD.t ->
  Uring.Region.chunk ->
  int ->
  int

read_upto fd chunk len reads at most len bytes from fd, returning as soon as some data is available.

parameter file_offset
Read from the given position in fd (default: 0).

raises End_of_file
Raised if all data has already been read.

val read_exactly : 
  ?file_offset:Optint.Int63.t ->
  FD.t ->
  Uring.Region.chunk ->
  int ->
  unit

read_exactly fd chunk len reads exactly len bytes from fd, performing multiple read operations if necessary.

parameter file_offset
Read from the given position in fd (default: 0).

raises End_of_file
Raised if the stream ends before len bytes have been read.

val readv : ?file_offset:Optint.Int63.t -> FD.t -> Cstruct.t list -> int

readv is like read_upto but can read into any cstruct(s), not just chunks of the pre-shared buffer.

If multiple buffers are given, they are filled in order.

val write : 
  ?file_offset:Optint.Int63.t ->
  FD.t ->
  Uring.Region.chunk ->
  int ->
  unit

write fd buf len writes exactly len bytes from buf to fd.

It blocks until the OS confirms the write is done, and resubmits automatically if the OS doesn't write all of it at once.

val writev : ?file_offset:Optint.Int63.t -> FD.t -> Cstruct.t list -> unit

writev is like write but can write from any cstruct(s), not just chunks of the pre-shared buffer.

If multiple buffers are given, they are sent in order. It will make multiple OS calls if the OS doesn't write all of it at once.

val writev_single : 
  ?file_offset:Optint.Int63.t ->
  FD.t ->
  Cstruct.t list ->
  int

writev_single is like writev but only performs a single write operation. It returns the number of bytes written, which may be smaller than the requested amount.

val splice : FD.t -> dst:FD.t -> len:int -> int

splice src ~dst ~len attempts to copy up to len bytes of data from src to dst.

returns
The number of bytes copied.

raises End_of_file
src is at the end of the file.

raises Unix.Unix_error(EINVAL,
"splice", _) if splice is not supported for these FDs.

val connect : FD.t -> Unix.sockaddr -> unit

connect fd addr attempts to connect socket fd to addr.

val await_readable : FD.t -> unit

await_readable fd blocks until fd is readable (or has an error).

val await_writable : FD.t -> unit

await_writable fd blocks until fd is writable (or has an error).

val fstat : FD.t -> Unix.stats

Like Unix.fstat.

val read_dir : FD.t -> string list

read_dir dir reads all directory entries from dir. The entries are not returned in any particular order (not even necessarily the order in which Linux returns them).

Sockets

val accept : sw:Eio.Std.Switch.t -> FD.t -> FD.t * Unix.sockaddr

accept ~sw t blocks until a new connection is received on listening socket t.

It returns the new connection and the address of the connecting peer. The new connection has the close-on-exec flag set automatically. The new connection is attached to sw and will be closed when that finishes, if not already closed manually by then.

val shutdown : FD.t -> Unix.shutdown_command -> unit

Like Unix.shutdown.

val send_msg : 
  FD.t ->
  ?fds:FD.t list ->
  ?dst:Unix.sockaddr ->
  Cstruct.t list ->
  unit

send_msg socket bufs is like writev socket bufs, but also allows setting the destination address (for unconnected sockets) and attaching FDs (for Unix-domain sockets).

val recv_msg : FD.t -> Cstruct.t list -> Uring.Sockaddr.t * int

recv_msg socket bufs is like readv socket bufs but also returns the address of the sender.

val recv_msg_with_fds : 
  sw:Eio.Std.Switch.t ->
  max_fds:int ->
  FD.t ->
  Cstruct.t list ->
  Uring.Sockaddr.t * int * FD.t list

recv_msg_with_fds is like recv_msg but also allows receiving up to max_fds file descriptors (sent using SCM_RIGHTS over a Unix domain socket).

Randomness

val getrandom : Cstruct.t -> int

getrandom buf reads some random bytes into buf and returns the number of bytes written.

It uses Linux's getrandom call, which is like reading from /dev/urandom except that it will block (the whole domain) if used at early boot when the random system hasn't been initialised yet.

DNS functions

val getaddrinfo : service:string -> string -> Eio.Net.Sockaddr.t list

getaddrinfo host returns a list of IP addresses for host. host is either a domain name or an ipaddress.