Choosing Between Lwt, Eio, and Domains for Concurrency in OCaml 5

Decision and constraints

When building an OCaml application you must decide how to handle concurrency and parallelism. The choice depends on three factors:

• Target OCaml version (pre‑5 vs. 5+).
• Whether the workload is I/O‑bound, CPU‑bound, or a mix.
• Existing codebase and library ecosystem maturity.

OCaml 5 introduced true parallelism via domains (OS threads sharing the GC heap) and effect handlers, which enable libraries like Eio. Earlier versions only provide cooperative threading via the runtime lock, so pre‑5 "threads" overlap I/O but not CPU work.

Comparison of supported options

Library / Approach	OCaml version	Concurrency model	Typical use case	Maturity / ecosystem
Lwt (or Async)	4.x and 5.x	Cooperative promises (monadic)	I/O‑bound services, legacy code	Mature, extensive bindings
Eio	5.x only	Effect‑handler based direct‑style structured concurrency	New I/O‑bound services on OCaml 5	Growing, API still evolving
Domains + Domainslib (or manual pool)	5.x only	Shared‑memory parallelism (OS threads)	CPU‑bound batch work, data‑parallel algorithms	Supported by official runtime; pool libraries available

Trade‑offs

Lwt/Async

Pros: works on all supported OCaml versions, large ecosystem, well‑understood failure handling via Lwt.cancel. Cons: forces monadic style (let* or >=), which can be "viral" and makes direct‑style code harder to compose.

Eio

Pros: eliminates monadic plumbing, provides scoped resources via Switch, cancellation is built‑in, and the API looks like synchronous code. Cons: requires OCaml 5, the library is younger (fewer third‑party adapters), and minor releases may introduce breaking changes.

Domains

Pros: enables true parallel CPU work by spreading OCaml code across OS threads; can be combined with an I/O stack (e.g., Eio or Lwt) for hybrid workloads. Cons: the shared heap means GC coordination can become a bottleneck for allocation‑heavy parallel code; speedup is workload‑dependent and must be measured.

Concrete implementation / validation sketch

Below are minimal skeletons for each approach using documented APIs. Pin library versions in your opam file; the snippets target OCaml 5.2+ with lwt.5.8, eio.1.0, and domainslib.0.5 (adjust as needed). They are illustrative; they have not been executed in this environment.

Lwt HTTP client example

(* file: lwt_client.ml *)
open Lwt
open Lwt.Infix
open Cohttp_lwt_unix.Client
open Cohttp

let fetch url =
  let%lwt (resp, body) = get (Uri.of_string url) in
  let%lwt body = Cohttp_lwt.Body.to_string body in
  Lwt.return (Response.status resp |> Code.code_of_status, body)

let () =
  let urls = [ "https://example.com/a"; "https://example.com/b" ] in
  let%lwt results = Lwt_list.map_p fetch urls in
  Lwt.iter (fun (status, body) ->
      Printf.printf "Status: %d\nBody length: %d\n" status (String.length body)
    ) results
  |> Lwt_main.run

To validate: compile with ocamlfind opt -package lwt.unix,cohttp-lwt-unix -linkpkg lwt_client.ml -o lwt_client, run against a local test server, and verify that cancelling a pending Lwt.wait (e.g., via Lwt.cancel) releases the file descriptor (check with lsof -p <pid>).

Eio TCP echo server example

(* file: eio_server.ml *)
open Eio
open Eio.Unix

let serve () =
  Switch.run (fun switch ->
    let listener = Net.listen switch (Tcp.Where_to_listen.of_port 8080) in
    let _ = Switch.fork switch (fun switch ->
        while true do
          let (src, _addr) = Net.accept switch listener in
          Switch.fork switch (fun switch ->
              try
                Flow.copy switch src src
              with
              | _ -> Flow.close src
            )
        done
      ) in
    Switch.await_any_exit switch
  )

let () = Eio_main.run serve

Validation steps: build with ocamlfind opt -package eio_main,eio.unix -linkpkg eio_server.ml -o eio_server, run the binary, connect with nc localhost 8080 and send lines; then send SIGINT to the process and observe that the switch exits and the socket is closed (check with lsof -i :8080 after termination).

Domains parallel map using Domainslib

(* file: parallel_map.ml *)
open Domainslib

let par_map f xs =
  let pool = Task.setup ~num_domains:(Domain.recommended_domain_count ()) () in
  let results = Array.make (Array.length xs) (Obj.magic 0) in
  Task.parallel_for pool ~start:0 ~finish:(Array.length xs) ~body:(fun i ->
      results.(i) <- f xs.(i)
    );
  Task.teardown pool;
  results

let () =
  let data = Array.init 1_000_000 (fun i -> i * i) in
  let squared = par_map (fun x -> x * x) data in
  Printf.printf "First 5 results: %s\n"
    (String.concat " " (Array.to_list (Array.sub squared 0 5) |> List.map string_of_int))

Validation: compile with ocamlfind opt -package domainslib -linkpkg parallel_map.ml -o parallel_map, run with time ./parallel_map and compare wall‑clock time against a sequential Array.map version. Verify speedup by varying the input size and observing whether the runtime scales with Domain.recommended_domain_count (). Note: allocation-heavy workloads may show limited speedup due to shared-heap GC coordination; profile with ocamlopt -p or perf before committing.

Practical decision rule

1. If you already maintain an Lwt/Async codebase and cannot migrate to OCaml 5, stay with Lwt/Async.
2. For a new I/O‑bound service targeting OCaml 5, start with Eio; it gives direct‑style code and built‑in cancellation.
3. For CPU‑bound batch processing on OCaml 5, use Domains (via Domainslib or a custom pool) and profile allocation patterns to ensure GC coordination does not erase gains.
4. Hybrid workloads can combine an I/O stack (Eio or Lwt) inside each domain, but avoid mixing Lwt and Eio directly in the same fiber without an explicit bridge.

Limitations and verification checklist

• Confirm the compiler version: ocaml -version must show ≥5.0.0 for Eio or Domains.
• Check Opam pinning: opam list lwt eio domainslib to ensure compatible versions are installed.
• Run a microbenchmark: compare sequential vs. N‑domain parallel map on realistic data; ensure observed speedup matches expectations for your allocation pattern.
• Test cancellation: spawn a long‑running fiber/task, trigger cancel, and verify that resources (file descriptors, sockets) are released (e.g., via lsof or netstat).
• Eio's API has evolved across releases; pin the version used in any example and expect churn in minor releases.