Hive.Mailbox

Bounded closeable FIFO mailboxes.

A bounded, closeable FIFO mailbox over Eio.Stream.

Bounded by construction: a full mailbox blocks producers (backpressure). Closing is a flag consulted by producers; consumers drain via take_opt during shutdown.

type 'a t

A mailbox carrying values of type 'a.

val create : int -> 'a t

create capacity makes a mailbox holding up to capacity messages. capacity = 0 is a synchronous handoff. Raises Invalid_argument if capacity is negative.

ocaml]
let inbox = Hive.Mailbox.create 128

val put : 'a t -> 'a -> (unit, [ `Closed ]) result

put t v enqueues v; blocks while the mailbox is full. Error Closed` once the mailbox is closed.

val take : 'a t -> 'a

take t dequeues the oldest message, blocking while empty.

Use this from the single consumer fiber that owns the mailbox.

val take_opt : 'a t -> 'a option

take_opt t dequeues without blocking; None when empty.

val close : 'a t -> unit

close t rejects subsequent puts. Queued messages remain takeable.

val is_closed : 'a t -> bool

is_closed t reports whether future puts will be rejected.

val length : 'a t -> int

Current queued message count. Intended for diagnostics and tests.

val capacity : 'a t -> int

Maximum queued message count configured at create.