Hive.Effects

Hive's small direct-style effect set.

The Hive effect set (deliberately small — design decision O3).

Effects are the dependency-injection mechanism for direct-style worker bodies: code running inside a worker may call sleep without threading a clock through every function. The runtime (Worker.spawn with a clock, or Server.Make.start) installs the handler; run installs it manually, e.g. in tests.

type Effect.t += 
  | Sleep : float -> unit Effect.t (* The effect performed by sleep. Most code should call sleep rather than performing Sleep directly. *)

val sleep : float -> unit

sleep seconds suspends the current fiber via the runtime's clock. Performing it outside an installed handler raises Effect.Unhandled.

ocaml]
let handler _self msg =
  Hive.Effects.sleep 0.250;
  traceln "delayed message: %s" msg

type clock = 
  | Clock : _ Eio.Time.clock -> clock (* Existential wrapper so runtimes can store a clock capability. *)

val run : clock:clock -> (unit -> 'a) -> 'a

run ~clock fn runs fn with the Hive effect handler installed. Unrecognized effects (e.g. Eio's own) propagate outward.

Use this in tests when calling code that uses sleep outside a worker:

ocaml]
Hive.Effects.run ~clock:(Hive.Effects.Clock clock) (fun () ->
  Hive.Effects.sleep 0.001)