Module `Uring`Source

Io_uring interface.

Sourcemodule Region : sig ... end

Region handles carving up a block of external memory into smaller chunks. This is currently just a slab allocator of a fixed size, on the basis that most IO operations operate on predictable chunks of memory. Since the block of memory in a region is contiguous, it can be used in Uring's fixed buffer model to map it into kernel space for more efficient IO.

Sourcetype 'a t

'a t is a reference to an Io_uring structure.

Sourcetype 'a job

A handle for a submitted job, which can be used to cancel it. If an operation returns None, this means that submission failed because the ring is full.

Source

val create : 
  ?fixed_buf_len:int ->
  ?polling_timeout:int ->
  queue_depth:int ->
  unit ->
  'a t

create ?fixed_buf_len ~queue_depth will return a fresh Io_uring structure t. Each t has associated with it a fixed region of memory that is used for the "fixed buffer" mode of io_uring to avoid data copying between userspace and the kernel.

parameter polling_timeout
If given, use polling mode with the given idle timeout (in ms). This requires privileges.

Sourceval queue_depth : 'a t -> int

queue_depth t returns the total number of submission slots for the uring t

Sourceval buf : 'a t -> Cstruct.buffer

buf t is the fixed internal memory buffer associated with uring t. You will normally want to wrap this with Region.alloc or similar to divide the buffer into chunks.

Sourceval realloc : 'a t -> Cstruct.buffer -> unit

realloc t buf will replace the internal fixed buffer associated with uring t with a fresh one.

raises Invalid_argument
if there are any requests in progress

Sourceval exit : 'a t -> unit

exit t will shut down the uring t. Any subsequent requests will fail.

raises Invalid_argument
if there are any requests in progress

Queueing operations

Sourceval noop : 'a t -> 'a -> 'a job option

noop t d submits a no-op operation to uring t. The user data d will be returned by wait or peek upon completion.

Sourcemodule type FLAGS = sig ... end

Sourcemodule Open_flags : sig ... end

Flags that can be passed to openat2.

Sourcemodule Resolve : sig ... end

Flags that can be passed to openat2 to control path resolution.

Source

val openat2 : 
  'a t ->
  access:[ `R | `W | `RW ] ->
  flags:Open_flags.t ->
  perm:Unix.file_perm ->
  resolve:Resolve.t ->
  ?fd:Unix.file_descr ->
  string ->
  'a ->
  'a job option

openat2 t ~access ~flags ~perm ~resolve ~fd path d opens path, which is resolved relative to fd (or the current directory if fd is not given). The user data d will be returned by wait or peek upon completion.

parameter access
controls whether the file is opened for reading, writing, or both

parameter flags
are the usual open flags

parameter perm
sets the access control bits for newly created files (subject to the process's umask)

parameter resolve
controls how the pathname is resolved.

Sourcemodule Poll_mask : sig ... end

Sourceval poll_add : 'a t -> Unix.file_descr -> Poll_mask.t -> 'a -> 'a job option

poll_add t fd mask d will submit a poll(2) request to uring t. It completes and returns d when an event in mask is ready on fd.

Sourcetype offset := Optint.Int63.t

For files, give the absolute offset, or use Optint.Int63.minus_one for the current position. For sockets, use an offset of Optint.Int63.zero (minus_one is not allowed here).

Source

val readv : 
  'a t ->
  file_offset:offset ->
  Unix.file_descr ->
  Cstruct.t list ->
  'a ->
  'a job option

readv t ~file_offset fd iov d will submit a readv(2) request to uring t. It reads from absolute file_offset on the fd file descriptor and writes the results into the memory pointed to by iov. The user data d will be returned by wait or peek upon completion.

Source

val writev : 
  'a t ->
  file_offset:offset ->
  Unix.file_descr ->
  Cstruct.t list ->
  'a ->
  'a job option

writev t ~file_offset fd iov d will submit a writev(2) request to uring t. It writes to absolute file_offset on the fd file descriptor from the the memory pointed to by iov. The user data d will be returned by wait or peek upon completion.

Source

val read_fixed : 
  'a t ->
  file_offset:offset ->
  Unix.file_descr ->
  off:int ->
  len:int ->
  'a ->
  'a job option

read t ~file_offset fd ~off ~len d will submit a read(2) request to uring t. It reads up to len bytes from absolute file_offset on the fd file descriptor and writes the results into the fixed memory buffer associated with uring t at offset off. The user data d will be returned by wait or peek upon completion.

Source

val read_chunk : 
  ?len:int ->
  'a t ->
  file_offset:offset ->
  Unix.file_descr ->
  Region.chunk ->
  'a ->
  'a job option

read_chunk is like read_fixed, but gets the offset from chunk.

parameter len
Restrict the read to the first len bytes of chunk.

Source

val write_fixed : 
  'a t ->
  file_offset:offset ->
  Unix.file_descr ->
  off:int ->
  len:int ->
  'a ->
  'a job option

write t ~file_offset fd off d will submit a write(2) request to uring t. It writes up to len bytes into absolute file_offset on the fd file descriptor from the fixed memory buffer associated with uring t at offset off. The user data d will be returned by wait or peek upon completion.

Source

val write_chunk : 
  ?len:int ->
  'a t ->
  file_offset:offset ->
  Unix.file_descr ->
  Region.chunk ->
  'a ->
  'a job option

write_chunk is like write_fixed, but gets the offset from chunk.

parameter len
Restrict the write to the first len bytes of chunk.

Source

val splice : 
  'a t ->
  src:Unix.file_descr ->
  dst:Unix.file_descr ->
  len:int ->
  'a ->
  'a job option

splice t ~src ~dst ~len d will submit a request to copy len bytes from src to dst. The operation returns the number of bytes transferred, or 0 for end-of-input. The result is EINVAL if the file descriptors don't support splicing.

Sourceval connect : 'a t -> Unix.file_descr -> Unix.sockaddr -> 'a -> 'a job option

connect t fd addr d will submit a request to connect fd to addr.

Sourcemodule Sockaddr : sig ... end

Holder for the peer's address in accept.

Sourceval accept : 'a t -> Unix.file_descr -> Sockaddr.t -> 'a -> 'a job option

accept t fd addr d will submit a request to accept a new connection on fd. The new FD will be configured with SOCK_CLOEXEC. The remote address will be stored in addr.

Sourceval close : 'a t -> Unix.file_descr -> 'a -> 'a job option

Sourceval cancel : 'a t -> 'a job -> 'a -> 'a job option

cancel t job d submits a request to cancel job. The cancel job itself returns 0 on success, or ENOTFOUND if job had already completed by the time the kernel processed the cancellation request.

raises Invalid_argument
if the job has already been returned by e.g. wait.

Submitting operations

Sourceval submit : 'a t -> int

submit t will submit all the outstanding queued requests on uring t to the kernel. Their results can subsequently be retrieved using wait or peek.

Sourcetype 'a completion_option =

| None
| Some of {
1. result : int;
2. data : 'a;
}

The type of results of calling wait and peek. None denotes that either there were no completions in the queue or an interrupt / timeout occurred. Some contains both the user data attached to the completed request and the integer syscall result.

Sourceval wait : ?timeout:float -> 'a t -> 'a completion_option

wait ?timeout t will block indefinitely (the default) or for timeout seconds for any outstanding events to complete on uring t. Events should have been queued via submit previously to this call.

Sourceval peek : 'a t -> 'a completion_option

peek t looks for completed requests on the uring t without blocking.

Sourceval error_of_errno : int -> Unix.error

error_of_errno e converts the error code abs e to a Unix error type.

Sourcemodule Private : sig ... end

Install

dune-project
Dependency

Authors

Maintainers

Sources

doc/uring/Uring/index.html

Module `Uring`Source

Queueing operations

Submitting operations

package uring

Install

dune-project Dependency

Authors

Maintainers

Sources

doc/uring/Uring/index.html

Module UringSource

Queueing operations

Submitting operations

dune-project
Dependency

Module `Uring`Source