Eio

https://ocaml-multicore.github.io/eio
Admin
Eio is a library for efficient, effect-based I/O in OCaml, providing a modern approach to...
Tokens:47,321
Snippets:623
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Eio_linux.run

Source: https://ocaml-multicore.github.io/eio/eio_linux/Eio_linux/index.html

Starts an event loop using Linux's io_uring backend.

```APIDOC
## val run

### Description
Runs an event loop using io_uring. This function initializes the io_uring and sets up a fixed buffer for I/O operations.

### Signature
`val run : ?queue_depth:int -> ?n_blocks:int -> ?block_size:int -> ?polling_timeout:int -> ?fallback:([ `Msg of string ] -> 'a) -> (stdenv -> 'a) -> 'a`

### Parameters
- **queue_depth** (int) - Optional - The depth of the io_uring queue.
- **n_blocks** (int) - Optional - Number of blocks for the fixed buffer.
- **block_size** (int) - Optional - Size of each block in the fixed buffer.
- **polling_timeout** (int) - Optional - Timeout for polling.
- **fallback** (([ `Msg of string ] -> 'a)) - Optional - Function to call if io_uring is unavailable.
- **fn** ((stdenv -> 'a)) - Required - The function to execute within the event loop.
```

--------------------------------

### Run a process and parse output

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Process/index.html

Example of using parse_out to execute a command and parse its standard output.

```ocaml
  # Eio_main.run @@ fun env ->
    let proc_mgr = Eio.Stdenv.process_mgr env in
    Eio.Process.parse_out proc_mgr Eio.Buf_read.line ["echo"; "hello"]
```

--------------------------------

### Connect to a TCP server and perform an HTTP GET request

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Net/index.html

Demonstrates establishing a TCP connection using a switch and performing a basic HTTP request.

```ocaml
  let addr = `Tcp (Ipaddr.V4.loopback, 8080)

  let http_get ~net ~stdout addr =
    Switch.run @@ fun sw ->
    let flow = Net.connect ~sw net addr in
    Flow.copy_string "GET / HTTP/1.0\r\n\r\n" flow;
    Flow.shutdown flow `Send;
    Flow.copy flow stdout
```

--------------------------------

### Create a sequence parser for lines

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Buf_read/index.html

Example showing how to use the seq combinator to parse a specific number of lines from a reader.

```ocaml
  let head n r =
    r |> Buf_read.(seq line) |> Seq.take n |> List.of_seq
```

--------------------------------

### sub

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Cancel/index.html

Installs a new cancellation context, runs a function within it, and restores the previous context upon completion.

```APIDOC
## val sub : (t -> 'a) -> 'a

### Description
`sub fn` installs a new cancellation context `t`, runs `fn t` inside it, and then restores the old context. If the old context is cancelled while `fn` is running then `t` is cancelled too.
```

--------------------------------

### Retrieve an interface implementation

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Resource/index.html

Use the get function to extract a specific interface implementation from a resource's handler.

```ocaml
  let write (Resource.T (t, ops)) bufs =
    let module X = (val (Resource.get ops Sink)) in
    X.write t bufs
```

--------------------------------

### Configure and use a mock flow

Source: https://ocaml-multicore.github.io/eio/eio/Eio_mock/index.html

Demonstrates creating mock stdin and stdout flows, configuring the stdin behavior with on_read, and performing a copy operation.

```ocaml
  let stdin = Eio_mock.Flow.make "stdin" in
  let stdout = Eio_mock.Flow.make "stdout" in
  Eio_mock.Flow.on_read stdin [
    `Return "chunk1";
    `Return "chunk2";
    `Raise End_of_file
  ];
  Eio.Flow.copy stdin stdout
```

--------------------------------

### Eio.Resource.close

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Resource/index.html

Closes a resource, preventing new operations from starting. If the resource is already closed, this function does nothing.

```APIDOC
## val close : [> close_ty ] t -> unit

### Description
`close t` marks the resource as closed. It can no longer be used after this. If `t` is already closed then this does nothing (it does not raise an exception).

### Note
If an operation is currently in progress when this is called then it is not necessarily cancelled, and any underlying OS resource (such as a file descriptor) might not be closed immediately if other operations are using it. Closing a resource only prevents new operations from starting.
```

--------------------------------

### Basic Stream Usage

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Stream/index.html

Demonstrates creating a stream, adding items, and taking them back.

```ocaml
  let t = Stream.create 100 in
  Stream.add t 1;
  Stream.add t 2;
  assert (Stream.take t = 1);
  assert (Stream.take t = 2)
```

--------------------------------

### Eio_main.run

Source: https://ocaml-multicore.github.io/eio/eio_main/Eio_main/index.html

Initializes the event loop and executes the provided function with the process environment.

```APIDOC
## val run : (Eio_unix.Stdenv.base -> 'a) -> 'a

### Description
Runs an event loop and executes the provided function `fn` within that loop. This function should be called once at the application entry point and must not be called by libraries.

### Parameters
- **fn** (Eio_unix.Stdenv.base -> 'a) - Required - The function to execute, which receives the process environment (file-system, network, etc.) as an argument.

### Usage
`Eio_main.run (fun env -> ...)`

### Notes
- The event loop implementation is selected automatically based on the platform (e.g., Eio_linux or Eio_posix).
- The backend can be overridden by setting the $EIO_BACKEND environment variable to "linux", "posix", or "windows".
```

--------------------------------

### Eio_posix.run

Source: https://ocaml-multicore.github.io/eio/eio_posix/Eio_posix/index.html

Initializes the POSIX event loop and executes the provided main function within that environment.

```APIDOC
## val run : (stdenv -> 'a) -> 'a

### Description
Runs an event loop and calls the provided `main` function with the POSIX standard environment (`stdenv`). Note that for portable applications, `Eio_main.run` is recommended instead.

### Parameters
- **main** ((stdenv -> 'a)) - Required - The function to execute within the event loop.
```

--------------------------------

### Run an Eio application with a filesystem subtree

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Stdenv/index.html

Initializes the Eio environment and restricts filesystem access to a specific subtree.

```ocaml
  let () =
    Eio_main.run @@ fun env ->
    Eio.Path.with_subtree env#fs "/srv/www" @@ fun www ->
    serve_files www
      ~net:env#net
```

--------------------------------

### Eio.Exn.create

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Exn/index.html

Creates an Io exception with an empty context.

```APIDOC
## val create : err -> exn

### Description
Creates an `Io` exception with an empty context from the provided error type.

### Parameters
- **err** (err) - The error type to wrap in an Io exception.
```

--------------------------------

### run_full

Source: https://ocaml-multicore.github.io/eio/eio/Eio_mock/Backend/index.html

Runs an event loop and provides a mock environment including clocks and backend identification.

```APIDOC
## val run_full : (stdenv -> 'a) -> 'a

### Description
Similar to run, but provides a mock environment (stdenv) to the function. The mock monotonic clock advances automatically when the system is idle.

### Parameters
- **fn** (stdenv -> 'a) - The function to execute, receiving the mock environment.

### stdenv Type
- **clock** (Clock.t)
- **mono_clock** (Clock.Mono.t)
- **debug** (Eio.Debug.t)
- **backend_id** (string)
```

--------------------------------

### spawn

Source: https://ocaml-multicore.github.io/eio/eio/Eio_unix/Process/Make_mgr/index.html

Spawns a new process with the specified configuration.

```APIDOC
## val spawn

### Signature
`val spawn : t -> sw:Eio.Switch.t -> ?cwd:Eio.Fs.dir_ty Eio.Path.t -> ?stdin:Eio.Flow.source_ty Eio.Std.r -> ?stdout:Eio.Flow.sink_ty Eio.Std.r -> ?stderr:Eio.Flow.sink_ty Eio.Std.r -> ?env:string array -> ?executable:string -> string list -> tag Eio.Process.ty Eio.Std.r`

### Description
Spawns a process using the manager. Supports optional configuration for working directory, standard streams, environment variables, and executable path.
```

--------------------------------

### Create and use a resource pool

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Pool/index.html

Initializes a pool with a fixed capacity and uses it to execute a function with a resource.

```ocaml
  let buffer_pool = Eio.Pool.create 10 (fun () -> Bytes.create 1024) in
  Eio.Pool.use buffer_pool (fun buf -> ...)
```

--------------------------------

### Create and Resolve a Promise

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Promise/index.html

Demonstrates creating a promise/resolver pair and using Fiber.both to await the result while resolving it concurrently.

```ocaml
  let promise, resolver = Promise.create () in
  Fiber.both
    (fun () -> traceln "Got %d" (Promise.await promise))
    (fun () -> Promise.resolve resolver 42)
```

--------------------------------

### create

Source: https://ocaml-multicore.github.io/eio/eio/Eio_utils/Zzz/index.html

Creates a new, empty timer queue.

```APIDOC
## val create : unit -> t

### Description
Creates a fresh empty timer queue.

### Signature
`create ()`
```

--------------------------------

### Using Eio.Buf_write with a flow

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Buf_write/index.html

Demonstrates initializing a buffer writer with a flow and performing sequential writes. The writer automatically flushes data to the underlying flow.

```ocaml
  module Write = Eio.Buf_write

  let () =
      Eio_mock.Backend.run @@ fun () ->
      let stdout = Eio_mock.Flow.make "stdout" in
      Write.with_flow stdout (fun w ->
          Write.string w "foo";
          Write.string w "bar";
          Eio.Fiber.yield ();
          Write.string w "baz";
      )
```

--------------------------------

### run

Source: https://ocaml-multicore.github.io/eio/eio/Eio_mock/Action/index.html

Executes a given action and returns the result.

```APIDOC
## val run : 'a t -> 'a

### Description
Performs the specified action `t` and returns the result.

### Signature
`val run : 'a t -> 'a`
```

--------------------------------

### make

Source: https://ocaml-multicore.github.io/eio/eio/Eio_mock/Clock/Mono/index.html

Creates a new mock clock instance initialized to 0.0.

```APIDOC
## val make : unit -> t

### Description
Creates a new mock clock instance. The time is initially set to 0.0 and remains static until manually advanced.

### Signature
`make () : t`
```

--------------------------------

### run_server

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Net/index.html

Establishes a concurrent or parallel socket server.

```APIDOC
## run_server

### Description
Establishes a server that accepts incoming connections and handles them concurrently. Supports optional parallel execution across multiple domains.

### Signature
`val run_server : ?max_connections:int -> ?additional_domains:(_ Domain_manager.t * int) -> ?stop:'a Promise.t -> on_error:(exn -> unit) -> [> 'tag listening_socket_ty ] Std.r -> [< 'tag stream_socket_ty ] connection_handler -> 'a`

### Parameters
- **max_connections** (int) - Optional - Maximum number of concurrent connections.
- **additional_domains** (Domain_manager.t * int) - Optional - Configuration for spawning additional domains for parallel processing.
- **stop** (Promise.t) - Optional - A promise that, when resolved, stops the server from accepting new connections.
- **on_error** (exn -> unit) - Required - Connection error handler.
```

--------------------------------

### listen

Source: https://ocaml-multicore.github.io/eio/eio_linux/Eio_linux/Low_level/index.html

Marks a socket as accepting connections.

```APIDOC
val listen : fd -> int -> unit
```

--------------------------------

### listen

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Net/Pi/module-type-NETWORK/index.html

Creates a listening socket on the specified address.

```APIDOC
## listen

### Signature
`val listen : t -> reuse_addr:bool -> reuse_port:bool -> backlog:int -> sw:Switch.t -> Sockaddr.stream -> tag listening_socket_ty Std.r`
```

--------------------------------

### Load a file from the filesystem

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Path/index.html

Accesses a file using the filesystem root provided by the environment.

```ocaml
  Eio.Path.load (fs / "/etc/passwd")
```

--------------------------------

### mkdir

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Path/index.html

Creates a new directory.

```APIDOC
## val mkdir : perm:File.Unix_perm.t -> _ t -> unit

### Description
Creates a new directory `t` with the specified permissions `perm`.
```

--------------------------------

### create

Source: https://ocaml-multicore.github.io/eio/eio/Eio_utils/Lf_queue/index.html

Creates a new empty lock-free queue.

```APIDOC
## val create : unit -> 'a t

### Description
Creates a new empty queue instance.

### Signature
`create ()`
```

--------------------------------

### create

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Private/Broadcast/index.html

Creates a new broadcast queue.

```APIDOC
## val create : unit -> t

### Description
Creates a fresh broadcast queue.

### Signature
`val create : unit -> t`
```

--------------------------------

### make

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Private/Cells/Make/index.html

Creates a fresh sequence of cells.

```APIDOC
## val make : unit -> 'a t

### Description
Creates a fresh sequence of cells ('a t).

### Parameters
- **unit** - Required - No parameters required.
```

--------------------------------

### spawn_unix

Source: https://ocaml-multicore.github.io/eio/eio/Eio_unix/Process/Make_mgr/index.html

Spawns a new process with Unix-specific configuration options.

```APIDOC
## val spawn_unix

### Signature
`val spawn_unix : t -> sw:Eio.Std.Switch.t -> ?cwd:Eio.Fs.dir_ty Eio.Path.t -> ?pgid:int -> ?uid:int -> ?gid:int -> ?login_tty:Fd.t -> env:string array -> fds:(int * Fd.t * Private.Fork_action.blocking) list -> executable:string -> string list -> ty Eio.Std.r`

### Description
Spawns a process with advanced Unix-specific settings such as process group ID, user/group IDs, and custom file descriptor mappings.
```

--------------------------------

### Create a sequence from a fiber using fork_seq

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Fiber/index.html

Demonstrates using fork_seq to produce a sequence of values from a fiber, which can then be consumed by another part of the program.

```ocaml
  Switch.run @@ fun sw ->
  let seq = Fiber.fork_seq ~sw (fun yield ->
      for i = 1 to 3 do
        traceln "Yielding %d" i;
        yield i
      done
    ) in
  Seq.iter (traceln "Got: %d") seq
```

--------------------------------

### make

Source: https://ocaml-multicore.github.io/eio/eio/Eio_mock/Flow/index.html

Creates a new mock Eio flow instance.

```APIDOC
## val make : ?pp:string Fmt.t -> string -> t

### Description
Creates a mock Eio flow. It can be used as a source, sink, or two-way flow.

### Parameters
- **pp** (string Fmt.t) - Optional - Printer to use to display the data.
- **label** (string) - Required - The label for the mock flow.
```

--------------------------------

### Eio.Resource.get_opt

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Resource/index.html

Retrieves the implementation of an interface if supported, otherwise returns None.

```APIDOC
## val get_opt : ('t, _) handler -> ('t, 'impl, _) pi -> 'impl option

### Description
`get_opt` is like `get`, but the handler need not have a compatible type. Instead, this performs a check at runtime and returns `None` if the interface is not supported.
```

--------------------------------

### Customizing Traceln with Fiber Bindings

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Debug/index.html

Demonstrates how to override the default traceln function using Fiber.with_binding to prepend a custom prefix to trace messages.

```ocaml
  open Eio.Std

  let my_traceln = {
    Eio.Debug.traceln = fun ?__POS__:_ fmt -> Fmt.epr ("[custom-trace] " ^^ fmt ^^ "@.")
  }

  let () =
    Eio_main.run @@ fun env ->
    let debug = Eio.Stdenv.debug env in
    Fiber.with_binding debug#traceln my_traceln @@ fun () ->
    traceln "Traced with custom function"
```

--------------------------------

### default_traceln

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Private/Debug/index.html

A suitable default implementation for Eio.Std.traceln.

```APIDOC
## val default_traceln

### Description
`default_traceln` is a suitable default implementation for `Eio.Std.traceln`. It writes output to stderr, prefixing each line with a "+". If `__POS__` is given, it also displays the file and line number from that. It uses `traceln_mutex` so that only one domain's output is written at a time.

### Signature
`val default_traceln : ?__POS__:(string * int * int * int) -> ('a, Stdlib.Format.formatter, unit, unit) Stdlib.format4 -> 'a`
```

--------------------------------

### install_sigchld_handler

Source: https://ocaml-multicore.github.io/eio/eio/Eio_unix/Process/index.html

Configures the signal handler for SIGCHLD to broadcast on the sigchld condition.

```APIDOC
## install_sigchld_handler

### Description
Sets the signal handler for SIGCHLD to broadcast to the `sigchld` condition. This is necessary for interoperability with non-Eio libraries that rely on SIGCHLD signals.
```

--------------------------------

### Eio.Process.run

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Process/index.html

Spawns a process and waits for it to complete, raising an exception if the exit status is not successful.

```APIDOC
## run

### Description
Executes a process and waits for it to finish. If the process fails, an exception is raised including the command that failed.

### Parameters
- **mgr** (mgr) - Required - The process manager.
- **args** (string list) - Required - The command and arguments to execute.
- **is_success** (int -> bool) - Optional - Function to determine if an exit code indicates success (default: code 0).
```

--------------------------------

### val spawn

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Process/Pi/module-type-MGR/index.html

Spawns a new process with optional configuration for environment, working directory, and standard streams.

```APIDOC
## val spawn

### Description
Spawns a new process using the provided manager, switch, and optional process configuration.

### Signature
`val spawn : t -> sw:Switch.t -> ?cwd:Fs.dir_ty Path.t -> ?stdin:Flow.source_ty Std.r -> ?stdout:Flow.sink_ty Std.r -> ?stderr:Flow.sink_ty Std.r -> ?env:string array -> ?executable:string -> string list -> tag ty Std.r`
```

--------------------------------

### create

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Mutex/index.html

Creates a new, initially unlocked mutex.

```APIDOC
## val create : unit -> t

### Description
Creates an initially unlocked mutex.

### Signature
`create () : t`
```

--------------------------------

### Create a buffered reader and read a line

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Buf_read/index.html

Initializes a buffered reader from a flow with a specified maximum size and reads a single line.

```ocaml
  let r = Buf_read.of_flow flow ~max_size:1_000_000 in
  Buf_read.line r
```

--------------------------------

### create

Source: https://ocaml-multicore.github.io/eio/eio/Eio_unix/Private/Thread_pool/index.html

Creates a new thread pool instance.

```APIDOC
## val create

### Description
Creates a new thread pool. The `sleep_q` parameter is used to register a clean-up task to finish idle threads.

### Signature
`val create : sleep_q:Eio_utils.Zzz.t -> t`
```

--------------------------------

### run

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Domain_manager/index.html

Runs a function in a newly-created domain and returns the result. Other fibers in the calling domain can run in parallel with the new domain.

```APIDOC
## val run : _ t -> (unit -> 'a) -> 'a

### Description
Runs a function `f` in a newly-created domain and returns the result. Other fibers in the calling domain can run in parallel with the new domain. If the calling fiber is cancelled, this is propagated to the spawned domain.

### Parameters
- **t** (_ t) - The domain manager resource.
- **f** (unit -> 'a) - The function to execute in the new domain.
```

--------------------------------

### Create a symbolic link

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Path/index.html

Creates a symbolic link at the specified path pointing to the target string.

```ocaml
  Eio.Path.symlink (dir / "current") ~link_to:"version-1.0"
```

--------------------------------

### Manage resource lifecycle with Switch.run

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Switch/index.html

Use Switch.run to create a scope where resources like file handles are automatically closed after the function completes.

```ocaml
   Switch.run (fun sw ->
      let flow = Dir.open_in ~sw dir "myfile.txt" in
      ...
   );
   (* [flow] will have been closed by this point *)
```

--------------------------------

### Save data to a file using Eio.Path

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Path/index.html

Demonstrates saving data to a file within the current working directory using the path operator.

```ocaml
  let ( / ) = Eio.Path.( / )

  let run dir =
    Eio.Path.save ~create:(`Exclusive 0o600)
      (dir / "output.txt") "the data"

  let () =
    Eio_main.run @@ fun env ->
    run (Eio.Stdenv.cwd env)
```

--------------------------------

### resume_all

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Private/Broadcast/index.html

Executes all non-cancelled callbacks in the queue.

```APIDOC
## val resume_all : t -> unit

### Description
Calls all non-cancelled callbacks attached to `t` in the order they were suspended. This function is lock-free and safe for use in signal handlers or GC finalizers.
```

--------------------------------

### connect

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Net/Pi/module-type-NETWORK/index.html

Establishes a stream connection to a remote address.

```APIDOC
## connect

### Signature
`val connect : t -> sw:Switch.t -> Sockaddr.stream -> tag stream_socket_ty Std.r`
```

--------------------------------

### accept_fork

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Net/index.html

Accepts a connection and handles it in a new fiber.

```APIDOC
## accept_fork

### Description
Accepts a connection and runs the provided handler in a new fiber. The flow is closed when the handler returns.

### Signature
`val accept_fork : sw:Switch.t -> [> 'tag listening_socket_ty ] Std.r -> on_error:(exn -> unit) -> [< 'tag stream_socket_ty ] connection_handler -> unit`

### Parameters
- **sw** (Switch.t) - Required - The switch to attach the new fiber to.
- **on_error** (exn -> unit) - Required - Callback invoked if the connection handler raises an exception.
```

--------------------------------

### connect

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Net/index.html

Establishes a new connection to a remote address.

```APIDOC
## connect

### Description
`connect ~sw t addr` creates a new socket connected to the specified remote address `addr`. The socket is automatically closed when the provided switch `sw` finishes.

### Signature
`val connect : sw:Switch.t -> [> 'tag ty ] t -> Sockaddr.stream -> 'tag stream_socket_ty Std.r`
```

--------------------------------

### process

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Process/Pi/index.html

Creates a resource handler for a process provider.

```APIDOC
## val process

### Description
Creates a resource handler for a given process provider module.

### Signature
`val process : (module PROCESS with type t = 't and type tag = 'tag) -> ('t, 'tag ty) Resource.handler`
```

--------------------------------

### Eio.Process.pipe

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Process/index.html

Creates a pipe backed by the OS, returning a source and a sink that can be used to connect processes.

```APIDOC
## Eio.Process.pipe

### Description
Creates a pipe backed by the OS. The resulting flows can be used by `spawn` without the need for extra fibers to copy the data, allowing for connecting multiple processes together.

### Signature
`val pipe : sw:Switch.t -> _ mgr -> [< Flow.source_ty | Resource.close_ty ] Std.r * [< Flow.sink_ty | Resource.close_ty ] Std.r`

### Parameters
- **sw** (Switch.t) - Required - The switch to manage the lifetime of the pipe resources.
- **mgr** (_ mgr) - Required - The process manager instance.
```

--------------------------------

### run_raw

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Domain_manager/Pi/module-type-MGR/index.html

Runs a function in a new domain without additional cancellation handling.

```APIDOC
## val run_raw : t -> (unit -> 'a) -> 'a

### Description
Runs a function `fn` in a new domain.

### Parameters
- **t** (t) - The domain manager instance.
- **fn** (unit -> 'a) - The function to execute in the new domain.
```

--------------------------------

### run_raw

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Domain_manager/index.html

Runs a function in a new domain without an event loop.

```APIDOC
## val run_raw : _ t -> (unit -> 'a) -> 'a

### Description
Runs a function `f` in a new domain, similar to `run`, but does not run an event loop in the new domain. Consequently, it cannot perform IO or fork fibers.

### Parameters
- **t** (_ t) - The domain manager resource.
- **f** (unit -> 'a) - The function to execute in the new domain.
```

--------------------------------

### val spawn_unix

Source: https://ocaml-multicore.github.io/eio/eio/Eio_unix/Process/Make_mgr/argument-1-X/index.html

Spawns a new Unix process using the provided process manager configuration and execution parameters.

```APIDOC
## val spawn_unix

### Description
Spawns a new Unix process. This function takes a process manager instance and various optional parameters to configure the execution environment, including working directory, process group, user/group IDs, and file descriptor mappings.

### Signature
`spawn_unix : t -> sw:Eio.Std.Switch.t -> ?cwd:Eio.Fs.dir_ty Eio.Path.t -> ?pgid:int -> ?uid:int -> ?gid:int -> ?login_tty:Fd.t -> env:string array -> fds:(int * Fd.t * Private.Fork_action.blocking) list -> executable:string -> string list -> ty Eio.Std.r`

### Parameters
- **t** (t) - The process manager instance.
- **sw** (Eio.Std.Switch.t) - The switch to manage the lifecycle of the process.
- **cwd** (Eio.Fs.dir_ty Eio.Path.t) - Optional working directory.
- **pgid** (int) - Optional process group ID.
- **uid** (int) - Optional user ID.
- **gid** (int) - Optional group ID.
- **login_tty** (Fd.t) - Optional file descriptor for login TTY.
- **env** (string array) - Environment variables for the process.
- **fds** ((int * Fd.t * Private.Fork_action.blocking) list) - List of file descriptor mappings.
- **executable** (string) - The path to the executable.
- **args** (string list) - List of command line arguments.
```

--------------------------------

### Create Process Resource Handler

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Process/Pi/index.html

Creates a handler for a process resource given a PROCESS module implementation.

```ocaml
val process :    (module PROCESS with type t = 't and type tag = 'tag) -> ('t, 'tag ty) Resource.handler
```

--------------------------------

### run

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Domain_manager/Pi/module-type-MGR/index.html

Runs a function in a new domain. If the calling fiber is cancelled, the provided cancelled promise resolves to the Cancel.Cancelled exception.

```APIDOC
## val run : t -> (cancelled:exn Promise.t -> 'a) -> 'a

### Description
Runs a function `fn` in a new domain. The function receives a `cancelled` promise that resolves if the calling fiber is cancelled, allowing the function to perform its own cancellation logic.

### Parameters
- **t** (t) - The domain manager instance.
- **fn** (cancelled:exn Promise.t -> 'a) - The function to execute in the new domain.
```

--------------------------------

### listening_socket_handler

Source: https://ocaml-multicore.github.io/eio/eio/Eio_unix/Pi/index.html

Creates a resource handler for a listening Unix socket.

```APIDOC
## listening_socket_handler

### Description
Creates a resource handler for a listening Unix socket.

### Signature
`val listening_socket_handler : (module LISTENING_SOCKET with type t = 't and type tag = 'tag) -> ('t, [ `Unix_fd | 'tag Eio.Net.listening_socket_ty ]) Eio.Resource.handler`
```

--------------------------------

### pp

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Exn/Backend/index.html

Pretty-prints a backend-specific exception.

```APIDOC
## val pp : t Fmt.t

### Description
Formats a backend-specific exception. If the global `show` reference is set to false, this function prints a placeholder instead of the actual error, which is useful for cross-backend expect-style testing.
```

--------------------------------

### accept

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Net/index.html

Waits for and accepts a new connection on a listening socket.

```APIDOC
## accept

### Description
Waits until a new connection is ready on the socket and returns it. The new socket is closed automatically when the switch finishes.

### Signature
`val accept : sw:Switch.t -> [> 'tag listening_socket_ty ] Std.r -> 'tag stream_socket_ty Std.r * Sockaddr.stream`

### Parameters
- **sw** (Switch.t) - Required - The switch to attach the new connection to.
- **socket** (listening_socket_ty) - Required - The listening socket to accept from.
```

--------------------------------

### Implementation of the parse function

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Buf_read/index.html

Shows the internal logic of the parse convenience function using a parser and end_of_input check.

```ocaml
  let buf = of_flow flow ~max_size in
  format_errors (p <* end_of_input) buf
```

--------------------------------

### create

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Buf_write/index.html

Creates a serializer with a fixed-length internal buffer.

```APIDOC
val create : ?sw:Switch.t -> int -> t
```

--------------------------------

### spawn

Source: https://ocaml-multicore.github.io/eio/eio_linux/Eio_linux/Low_level/Process/index.html

Forks a child process that executes the provided actions.

```APIDOC
## spawn

### Description
Forks a child process, which executes the provided actions. The last action should be `Fork_action.execve`.

### Signature
`val spawn : sw:Eio.Std.Switch.t -> Fork_action.t list -> t`

### Parameters
- **sw** (Eio.Std.Switch.t) - Required - The child will be sent `Sys.sigkill` if this switch finishes.
- **actions** (Fork_action.t list) - Required - Setup actions to perform in the child process.
```

--------------------------------

### Eio_unix.Fd.use

Source: https://ocaml-multicore.github.io/eio/eio/Eio_unix/Fd/index.html

Executes a function using the wrapped file descriptor, ensuring it remains open during the operation.

```APIDOC
## val use : t -> (Unix.file_descr -> 'a) -> if_closed:(unit -> 'a) -> 'a

### Description
Calls the provided function `fn` with the underlying `Unix.file_descr`. It ensures the file descriptor is not closed while the function is executing. If the wrapper is already closed, the `if_closed` callback is executed instead.
```

--------------------------------

### Create an Executor Pool

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Executor_pool/index.html

Initializes an executor pool within an Eio environment, typically at application startup.

```ocaml
  let () =
    Eio_main.run @@ fun env ->
    Switch.run @@ fun sw ->
    let pool =
      Eio.Executor_pool.create
        ~sw (Eio.Stdenv.domain_mgr env)
        ~domain_count:4
    in
    main ~pool
```

--------------------------------

### use

Source: https://ocaml-multicore.github.io/eio/eio_linux/Eio_linux/Low_level/Fixed/index.html

Executes a function with a temporary chunk.

```APIDOC
## val use : fallback:(unit -> 'a) -> (chunk -> 'a) -> 'a

### Description
Runs the provided function with a freshly allocated chunk and automatically frees it afterwards. If no chunks are available, the fallback function is executed instead.
```

--------------------------------

### Eio_mock.Net Functions

Source: https://ocaml-multicore.github.io/eio/eio/Eio_mock/Net/index.html

Functions for creating and configuring mock network components.

```APIDOC
## val make

### Description
Creates a new mock network instance.

### Signature
`val make : string -> t`

## val on_connect

### Description
Configures the behavior when a client attempts to connect to the mock network.

### Signature
`val on_connect : t -> _ Eio.Net.stream_socket Handler.actions -> unit`

## val on_listen

### Description
Configures the behavior when a server starts listening on the mock network.

### Signature
`val on_listen : t -> _ Eio.Net.listening_socket Handler.actions -> unit`

## val on_datagram_socket

### Description
Configures how datagram sockets are created within the mock network.

### Signature
`val on_datagram_socket : t -> _ Eio.Net.datagram_socket Handler.actions -> unit`

## val listening_socket

### Description
Creates a mock listening socket that can be configured to provide mock connections.

### Signature
`val listening_socket : ?listening_addr:Eio.Net.Sockaddr.stream -> string -> listening_socket`

## val on_accept

### Description
Configures the response behavior when the server calls 'accept' on a listening socket.

### Signature
`val on_accept : listening_socket -> (Flow.t * Eio.Net.Sockaddr.stream) Handler.actions -> unit`
```

--------------------------------

### load

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Path/index.html

Reads the entire contents of a file.

```APIDOC
## val load : _ t -> string

### Description
Returns the contents of the given file. This is a convenience wrapper around `with_open_in`.
```

--------------------------------

### Create Socket Resource Handlers

Source: https://ocaml-multicore.github.io/eio/eio/Eio_unix/Pi/index.html

Functions to create resource handlers for flow, datagram, and listening sockets.

```ocaml
val flow_handler :    (module FLOW with type t = 't and type tag = 'tag) -> ('t, [ `Unix_fd | 'tag Eio.Net.stream_socket_ty | Eio.File.rw_ty ]) Eio.Resource.handler
```

```ocaml
val datagram_handler :    (module DATAGRAM_SOCKET with type t = 't and type tag = 'tag) -> ('t, [ `Unix_fd | 'tag Eio.Net.datagram_socket_ty ]) Eio.Resource.handler
```

```ocaml
val listening_socket_handler :    (module LISTENING_SOCKET with type t = 't and type tag = 'tag) -> ('t, [ `Unix_fd | 'tag Eio.Net.listening_socket_ty ]) Eio.Resource.handler
```

--------------------------------

### setsockopt / getsockopt

Source: https://ocaml-multicore.github.io/eio/eio/Eio_unix/Pi/module-type-FLOW/index.html

Sets or retrieves socket options.

```APIDOC
val setsockopt : t -> 'a Eio.Net.Sockopt.t -> 'a -> unit
val getsockopt : t -> 'a Eio.Net.Sockopt.t -> 'a
```

--------------------------------

### Implementing Condition Waiting with Mutex

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Condition/index.html

Demonstrates using a mutex and condition variable to wait for a shared variable to reach a specific state.

```ocaml
  let x = ref 0
  let cond = Eio.Condition.create ()
  let mutex = Eio.Mutex.create ()

  let set_x value =
    Eio.Mutex.use_rw ~protect:false mutex (fun () -> x := value);
    Eio.Condition.broadcast cond

  let await_x p =
    Eio.Mutex.use_ro mutex (fun () ->
       while not (p !x) do                  (* [x] cannot change, as mutex is locked. *)
         Eio.Condition.await cond mutex     (* Mutex is unlocked while suspended. *)
       done
    )
```

```ocaml
  Fiber.both
    (fun () ->
       traceln "x = %d" !x;
       await_x ((=) 42);
       traceln "x = %d" !x
    )
    (fun () ->
       set_x 5;
       Fiber.yield ();
       set_x 7;
       set_x 42;
    )
```

--------------------------------

### Output debug messages with traceln

Source: https://ocaml-multicore.github.io/eio/eio/Eio/index.html

Use traceln for quick debugging output to stderr. It is safe for concurrent use across multiple domains and flushes automatically.

```ocaml
  traceln "x = %d" x;
  traceln "x = %d" x ~__POS__;   (* With location information *)
```

--------------------------------

### symlink

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Path/index.html

Creates a symbolic link.

```APIDOC
## val symlink : link_to:string -> _ t -> unit

### Description
Creates a symbolic link t pointing to link_to.
```

--------------------------------

### Define Eio_unix.Private modules

Source: https://ocaml-multicore.github.io/eio/eio/Eio_unix/Private/index.html

Utility modules for managing file descriptors, process forking, and thread pools.

```ocaml
module Rcfd : sig ... end
A safe wrapper around `Unix.file_descr`.
module Fork_action : sig ... end
Actions to perform after forking a child process.
module Thread_pool : sig ... end
A pool of systhreads, to avoid the overhead of creating a new thread for each operation.
```

--------------------------------

### Eio.Pool.use

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Pool/index.html

Uses a resource from the pool and returns it after the operation completes.

```APIDOC
## val use : ?never_block:bool -> 'a t -> ('a -> 'b) -> 'b

### Description
Waits for a resource to be available from the pool, executes the provided function with that resource, and ensures the resource is returned to the pool afterwards.

### Parameters
- **t** ('a t) - Required - The resource pool.
- **fn** ('a -> 'b) - Required - The function to execute using the resource.
- **never_block** (bool) - Optional - If true, creates a fresh resource if the pool is at capacity to avoid waiting. This resource is disposed immediately after use.
```

--------------------------------

### add

Source: https://ocaml-multicore.github.io/eio/eio/Eio_utils/Zzz/index.html

Adds a new event to the timer queue.

```APIDOC
## val add : t -> Mtime.t -> item -> Key.t

### Description
Adds a new event, due at the specified time, and returns its ID (Key.t).

### Parameters
- **t** (t) - The timer queue.
- **time** (Mtime.t) - The time at which the item is due.
- **item** (item) - The item to schedule (Fiber or Fn).
```

--------------------------------

### connect

Source: https://ocaml-multicore.github.io/eio/eio_linux/Eio_linux/Low_level/index.html

Attempts to connect a socket file descriptor to a specified address.

```APIDOC
## connect

### Signature
`val connect : fd -> Unix.sockaddr -> unit`

### Description
Attempts to connect socket `fd` to `addr`.
```

--------------------------------

### await_batch

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Buf_write/index.html

Returns a list of buffers that should be written. Waits if no data is available.

```APIDOC
val await_batch : t -> Cstruct.t list
```

--------------------------------

### with_tcp_connect

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Net/index.html

Creates a TCP connection to a host and service, executes a function, and ensures the connection is closed afterwards.

```APIDOC
## with_tcp_connect

### Description
`with_tcp_connect ~host ~service t f` creates a TCP connection to the specified host and service, then executes the function `f` with the connection. The connection is closed automatically after `f` returns.

### Signature
`val with_tcp_connect : ?timeout:Time.Timeout.t -> host:string -> service:string -> [> 'tag ty ] Std.r -> ('tag stream_socket_ty Std.r -> 'b) -> 'b`
```

--------------------------------

### Eio.Stream.take

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Stream/index.html

Takes the next item from the stream, blocking if empty.

```APIDOC
## val take : 'a t -> 'a

### Description
Takes the next item from the head of the stream. If no items are available, it waits until one becomes available.
```

--------------------------------

### Eio.Exn.combine

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Exn/index.html

Combines two exceptions into a single exception.

```APIDOC
## val combine : with_bt -> with_bt -> with_bt

### Description
Returns a single exception and backtrace representing two errors. It uses heuristics to simplify the result, such as ignoring `Cancel.Cancelled` exceptions or merging multiple `Io` errors into a `Multiple_io` structure.
```

--------------------------------

### Eio.File Operations

Source: https://ocaml-multicore.github.io/eio/eio/Eio/File/index.html

Methods for interacting with open file resources in Eio.

```APIDOC
## stat

### Description
Returns the `Stat.t` record associated with the file.

### Signature
`val stat : _ ro -> Stat.t`

## size

### Description
Returns the size of the file.

### Signature
`val size : _ ro -> Optint.Int63.t`

## pread

### Description
Performs a single read of the file at a specific offset into the provided buffers.

### Signature
`val pread : _ ro -> file_offset:Optint.Int63.t -> Cstruct.t list -> int`

## pread_exact

### Description
Reads from the file into buffers until the buffers are full. Raises `End_of_file` if the buffer could not be filled.

### Signature
`val pread_exact : _ ro -> file_offset:Optint.Int63.t -> Cstruct.t list -> unit`

## pwrite_single

### Description
Performs a single write operation, writing data from buffers to a specific location in the file.

### Signature
`val pwrite_single : _ rw -> file_offset:Optint.Int63.t -> Cstruct.t list -> int`

## pwrite_all

### Description
Writes all the data in the provided buffers to a specific location in the file.

### Signature
`val pwrite_all : _ rw -> file_offset:Optint.Int63.t -> Cstruct.t list -> unit`

## seek

### Description
Sets and/or gets the current file position, similar to `Unix.lseek`.

### Signature
`val seek : _ ro -> Optint.Int63.t -> [ `Set | `Cur | `End ] -> Optint.Int63.t`

## sync

### Description
Flushes file buffers to disk, similar to `Unix.fsync`.

### Signature
`val sync : _ rw -> unit`

## truncate

### Description
Sets the length of a file, similar to `Unix.ftruncate`.

### Signature
`val truncate : _ rw -> Optint.Int63.t -> unit`
```

--------------------------------

### Eio.Pool.create

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Pool/index.html

Creates a new resource pool with a specified capacity and allocation function.

```APIDOC
## val create : ?validate:('a -> bool) -> ?dispose:('a -> unit) -> int -> (unit -> 'a) -> 'a t

### Description
Creates a fresh pool which allows up to n resources to be live at a time. It uses the provided alloc function to create new resources as needed.

### Parameters
- **n** (int) - Required - The maximum number of resources allowed to be live at a time.
- **alloc** (unit -> 'a) - Required - Function used to create new resources.
- **validate** ('a -> bool) - Optional - Function used to check each resource before use. If it returns false, the resource is disposed and a fresh one is allocated.
- **dispose** ('a -> unit) - Optional - Function used to free resources rejected by validate.
```

--------------------------------

### Define File Resource Capabilities

Source: https://ocaml-multicore.github.io/eio/eio/Eio/File/Pi/index.html

Defines the resource capabilities for read and write operations within the Eio framework.

```ocaml
type Resource.pi += 
  1. | Read : ('t, (module READ with type t = 't), [> ro_ty ]) Resource.pi
  2. | Write : ('t, (module WRITE with type t = 't), [> rw_ty ]) Resource.pi
```

--------------------------------

### Eio.Resource.get

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Resource/index.html

Retrieves the implementation of a specific interface from a resource handler.

```APIDOC
## val get : ('t, 'tags) handler -> ('t, 'impl, 'tags) pi -> 'impl

### Description
`get handler iface` uses `handler` to get the implementation of `iface`.
```

--------------------------------

### pipe

Source: https://ocaml-multicore.github.io/eio/eio/Eio_unix/Process/Pi/module-type-MGR/index.html

Creates a pipe for process communication.

```APIDOC
## val pipe

### Description
Creates a new pipe, returning a source and a sink for communication.

### Signature
`val pipe : t -> sw:Eio.Switch.t -> [ Eio.Flow.source_ty | Eio.Resource.close_ty ] Eio.Std.r * [ Eio.Flow.sink_ty | Eio.Resource.close_ty ] Eio.Std.r`
```

--------------------------------

### Eio.Process.parse_out

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Process/index.html

Runs a process and parses its standard output using a provided buffer reader parser.

```APIDOC
## parse_out

### Description
Runs the specified command and parses the child's stdout with the provided parser. It waits for the process to finish and checks that the exit status is successful.

### Parameters
- **mgr** (mgr) - Required - The process manager.
- **parser** (Buf_read.parser) - Required - The parser to consume the process output.
- **args** (string list) - Required - The command and arguments to execute.
```

--------------------------------

### val any

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Net/Ipaddr/V4/index.html

Represents all Internet addresses available on the host machine. This is intended for use with listen operations.

```APIDOC
## val any

### Description
A special IPv4 address representing all the Internet addresses that the host machine possesses. This value is intended for use only with `listen` operations.

### Signature
`val any : [> `V4 ] t`
```

--------------------------------

### Eio_posix.Low_level API

Source: https://ocaml-multicore.github.io/eio/eio_posix/Eio_posix/Low_level/index.html

A collection of low-level POSIX-compatible functions for file and socket operations.

```APIDOC
## Functions

### await_readable
`val await_readable : string -> fd -> unit`
Suspends the fiber until the file descriptor is readable.

### await_writable
`val await_writable : string -> fd -> unit`
Suspends the fiber until the file descriptor is writable.

### sleep_until
`val sleep_until : Mtime.t -> unit`
Suspends the fiber until the specified time.

### socket
`val socket : sw:Eio.Std.Switch.t -> Unix.socket_domain -> Unix.socket_type -> int -> fd`
Creates a new socket and attaches it to the provided switch.

### openat
`val openat : sw:Eio.Std.Switch.t -> mode:int -> dir_fd -> string -> Open_flags.t -> fd`
Opens a file relative to a directory file descriptor. The returned FD is non-blocking and close-on-exec.

### read / write
`val read : fd -> bytes -> int -> int -> int`
`val write : fd -> bytes -> int -> int -> int`
Standard read and write operations on a file descriptor.

### connect
`val connect : fd -> Unix.sockaddr -> unit`
Connects a socket to a remote address.

### accept
`val accept : sw:Eio.Std.Switch.t -> fd -> fd * Unix.sockaddr`
Accepts a new connection on a socket.
```

--------------------------------

### fd

Source: https://ocaml-multicore.github.io/eio/eio/Eio_unix/Resource/index.html

Returns the file descriptor being wrapped by a resource.

```APIDOC
## val fd : _ t -> Fd.t

### Description
Returns the FD being wrapped by a resource.

### Parameters
- **t** (_ t) - Required - The resource to extract the file descriptor from.
```

--------------------------------

### next_resume

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Private/Cells/Make/index.html

Atomically returns the next resume cell.

```APIDOC
## val next_resume : 'a t -> 'a Cell.t Stdlib.Atomic.t

### Description
Atomically returns the next resume cell. If multiple domains call this simultaneously, each receives a unique cell.

### Parameters
- **t** ('a t) - Required - The sequence of cells.
```

--------------------------------

### val any

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Net/Ipaddr/V6/index.html

Represents all Internet addresses available on the host machine. This is typically used when configuring a server to listen on all interfaces.

```APIDOC
## val any

### Description
A special IPv6 address representing all the Internet addresses that the host machine possesses. It is intended for use with `listen` operations.

### Signature
`val any : [> `V6 ] t`
```

--------------------------------

### openat

Source: https://ocaml-multicore.github.io/eio/eio_linux/Eio_linux/Low_level/index.html

Opens a file relative to a directory file descriptor.

```APIDOC
## val openat : sw:Eio.Std.Switch.t -> ?seekable:bool -> access:[ `R | `W | `RW ] -> flags:Uring.Open_flags.t -> perm:Unix.file_perm -> dir_fd -> string -> fd

### Description
Opens `dir/path` using the provided access, flags, and permissions.
```

--------------------------------

### Eio.Process.spawn

Source: https://ocaml-multicore.github.io/eio/eio/Eio/Process/index.html

Creates a new child process connected to a switch. The process is automatically terminated when the switch is released.

```APIDOC
## spawn

### Description
Creates a new child process that is connected to the switch `sw`. The child process will be sent `Sys.sigkill` when the switch is released.

### Parameters
- **sw** (Switch.t) - Required - The switch to attach the process to.
- **mgr** (mgr_ty) - Required - The process manager.
- **args** (string list) - Required - The command and arguments to execute.
- **cwd** (Path.t) - Optional - The current working directory of the process.
- **stdin** (Flow.source) - Optional - The flow to attach to the process's standard input.
- **stdout** (Flow.sink) - Optional - A flow that the process's standard output goes to.
- **stderr** (Flow.sink) - Optional - A flow that the process's standard error goes to.
- **env** (string array) - Optional - The environment for the process.
- **executable** (string) - Optional - The path of the executable to run.
```
Tokens:
Raw