eio

Eio Concurrency

Core Concepts

Why Eio

Eio is an effects-based IO library for OCaml 5. Advantages over Lwt/Async:

• Direct-style code: No monads, concurrent code looks like sequential code
• Performance: Real stacks, no heap allocations to simulate continuations
• Better backtraces: Exceptions show proper call traces
• Platform optimization: Generic API with optimized backends (Linux io_uring, POSIX, Windows)

Capability-Based Design

Pass capabilities explicitly instead of using global resources:

type t = {
  net : _ Eio.Net.t;
  clock : _ Eio.Time.clock;
  fs : _ Eio.Path.t;
}

(* Function signature reveals what resources it needs *)
val connect : net:_ Eio.Net.t -> host:string -> connection

Do: Pass net, clock, fs explicitly—makes dependencies clear and testable.

Don't: Use global modules like Unix.gettimeofday or access ambient resources.

Structured Concurrency with Switches

Eio.Switch.run manages resource and fiber lifecycles:

Eio.Switch.run @@ fun sw ->
  let conn = connect ~sw server in
  (* conn automatically closed when sw exits *)
  process conn

Do: Create switches in the smallest possible scope.

Don't: Take a switch argument if you could create one internally.

Fibers

Lightweight concurrent units running on a single core:

(* Run two operations concurrently *)
Eio.Fiber.both
  (fun () -> download file1)
  (fun () -> download file2)

(* Only one fiber executes at a time until one performs an effect *)

Cancellation

Cancellation contexts form a tree. Uncaught exceptions propagate upward, cancelling siblings:

(* If one branch fails, the other gets Cancelled *)
Eio.Fiber.both
  (fun () -> may_fail ())
  (fun () -> other_work ())  (* receives Cancelled if may_fail raises *)

Use Cancel.protect for operations that must complete:

Eio.Cancel.protect @@ fun () ->
  (* This won't be cancelled even if parent is *)
  flush_and_close connection