Hive.Task

One-shot background work with observable outcomes.

One-shot background work — the "don't block the request" case.

Thin over Eio.Fiber + Eio.Promise, returning Outcome.t so callers and supervisors can distinguish completion, failure and cancellation.

type 'a t

A running one-shot task that will eventually produce an 'a Outcome.t.

val async : sw:Eio.Switch.t -> (unit -> 'a) -> 'a t

async ~sw fn runs fn in a fiber under sw.

ocaml]
let task = Hive.Task.async ~sw (fun () -> expensive_work ())

val outcome : 'a t -> 'a Outcome.t Eio.Promise.t

Resolved exactly once when the task finishes.

Use this when composing with other Eio promises instead of blocking with await.

val await : 'a t -> 'a Outcome.t

await t blocks until the task finishes.

ocaml]
match Hive.Task.await task with
| Hive.Outcome.Completed value -> value
| Hive.Outcome.Failed exn -> raise exn
| Hive.Outcome.Cancelled -> invalid_arg "task cancelled"

val await_all : 'a t list -> 'a Outcome.t list

Await every task, preserving order.

The result list has the same order and length as the input list, regardless of which task finished first.

val cancel : 'a t -> unit

Cancel the task's fiber; its outcome resolves to Cancelled. A no-op once the task has finished.