Runtime_events.Callbacks(3)

🎀 Runtime_events.Callbacks 🎀

okay so bestie, you're on the Runtime_events.Callbacks page from the OCaml library manual, and the vibe is callback central 💅✨ It's a tiny module, but it's got main character energy fr fr.

---

✨ NAME ✨

Runtime_events.Callbacks — no description. Yep, that's literally all it says. No cap. 🙈

---

🦋 Module 🦋

The module line is right here:

Module   Runtime_events.Callbacks

Short and sweet, periodt. 🫶

---

💖 Documentation 💖

🌸 Module Callbacks 🌸

Module Callbacks
 : sig end

This is the module signature, and it ends immediately. Iconic minimalism, honestly. 🎀

🌟 type t 🌟

type t — Type of callbacks. That's the whole official note, and it ate. 💅

👑 val create 👑

val create : ?runtime_begin:(int -> Runtime_events.Timestamp.t ->
Runtime_events.runtime_phase -> unit) -> ?runtime_end:(int ->
Runtime_events.Timestamp.t -> Runtime_events.runtime_phase -> unit) ->
?runtime_counter:(int -> Runtime_events.Timestamp.t ->
Runtime_events.runtime_counter -> int -> unit) -> ?alloc:(int ->
Runtime_events.Timestamp.t -> int array -> unit) -> ?lifecycle:(int ->
Runtime_events.Timestamp.t -> Runtime_events.lifecycle -> int option ->
unit) -> ?lost_events:(int -> int -> unit) -> unit -> t

This creates a callback that optionally subscribes to one or more runtime events. Obsessed with the flexibility, ngl. 🦋

The optional callback subscriptions are these cuties — all optional, all with their exact callback types:

• ?runtime_begin — (int -> Runtime_events.Timestamp.t -> Runtime_events.runtime_phase -> unit)
• ?runtime_end — (int -> Runtime_events.Timestamp.t -> Runtime_events.runtime_phase -> unit)
• ?runtime_counter — (int -> Runtime_events.Timestamp.t -> Runtime_events.runtime_counter -> int -> unit)
• ?alloc — (int -> Runtime_events.Timestamp.t -> int array -> unit)
• ?lifecycle — (int -> Runtime_events.Timestamp.t -> Runtime_events.lifecycle -> int option -> unit)
• ?lost_events — (int -> int -> unit)

The first int supplied to callbacks is the ring buffer index. Each domain owns a single ring buffer for the duration of the domain's existence. After a domain terminates, a newly spawned domain may take ownership of the ring buffer. That's the whole ring-buffer tea ☕✨

A runtime_begin callback is called when the runtime enters a new phase (e.g. a runtime_begin with EV_MINOR is called at the start of a minor GC). A runtime_end callback is called when the runtime leaves a certain phase. The runtime_counter callback is called when a counter is emitted by the runtime. lifecycle callbacks are called when the ring undergoes a change in lifecycle and a consumer may need to respond. alloc callbacks are currently only called on the instrumented runtime. lost_events callbacks are called if the consumer code detects some unconsumed events have been overwritten.

Heads up bestie: that lost_events one is literally the “some unconsumed events got overwritten” callback. So if it fires, the consumer code detected it. 💀

🧚 val add_user_event 🧚

val add_user_event : 'a Runtime_events.Type.t -> (int ->
Runtime_events.Timestamp.t -> 'a Runtime_events.User.t -> 'a -> unit) ->
t -> t

add_user_event ty callback t extends t to additionally subscribe to user events of type ty. When such an event happens, callback is called with the corresponding event and payload. Slay. 🫶🔥

---

xoxo, OCamldoc · 2026-06-22 · this was the Runtime_events.Callbacks(3) page, mwah 💋🎀