documentation about runtime events

raphael-proust · raphael-proust · commit 14dc69ea552c · 2025-12-04T15:10:01.000+01:00
diff --git a/src/core/lwt.mli b/src/core/lwt.mli
@@ -2077,4 +2077,6 @@ module Private : sig
   end
 end [@@alert trespassing "for internal use only, keep away"]
 
+(** [Lwt.with_key tracing_context (Some name) (fun () -> <e>)] causes the span
+    events emitted inside of <e> to bear the name [name]. *)
 val tracing_context : string key
diff --git a/src/core/lwt_rte.mli b/src/core/lwt_rte.mli
@@ -1,3 +1,10 @@
+(** All the functions below are wrappers around the ones found in
+    [Lwt_runtime_events]. The wrappers conditionally call the correspoding
+    wrapped function or do nothing, depending if the [Lwt_runtime_events] library
+    is available.
+
+    Note that [Lwt_runtime_events] is only installable with OCaml 5.1+ *)
+
 val emit_paused_count : int -> unit
 val emit_sch_call_begin : unit -> unit
 val emit_sch_call_end : unit -> unit
diff --git a/src/runtime_events/lwt_runtime_events.mli b/src/runtime_events/lwt_runtime_events.mli
@@ -1,16 +1,28 @@
+(** This is the runtime-events library for lwt. It contains lwt-specific
+    definition of events (so that programs can be written to consume the events
+    lwt produces) and the function to emit them (so that lwt can emit them). This
+    library is not intended for emitting events by hand. *)
+
+(** Counter event indicatiing the number of paused promise, i.e., the number of
+    calls to [Lwt.pause] which have not yet been resolved. *)
 type Runtime_events.User.tag += Paused_count
 val paused_count : int Runtime_events.User.t
 val emit_paused_count : int -> unit
 
+(** Span event indicatiing that [Lwt_main.run] has been called and hasn't
+    returned yet, i.e., when the Lwt scheduler is running. *)
 type Runtime_events.User.tag += Scheduler_call
 val sch_call : Runtime_events.Type.span Runtime_events.User.t
 val emit_sch_call_begin : unit -> unit
 val emit_sch_call_end : unit -> unit
 
+(** Punctual event indicatiing that the scheduler is performing one loop. *)
 type Runtime_events.User.tag += Scheduler_lap
 val sch_lap : unit Runtime_events.User.t
 val emit_sch_lap : unit -> unit
 
+(** Counter event indicatiing the number of unix I/O jobs, i.e., the number of
+    calls to [Lwt_unix.*] which have not yet been resolved. *)
 type Runtime_events.User.tag += Unix_job_count
 val unix_job_count : int Runtime_events.User.t
 val emit_job_count : int -> unit
@@ -19,6 +31,9 @@ module Trace : sig
   type t = { kind: Runtime_events.Type.span; context: string option; filename: string; line: int; }
   val t : t Runtime_events.Type.t
 
+  (** Span event indicatiing that a promise is taking time to resolve. The
+      event indicates the location of the bind for the promise. These events are
+      automatically emitted by code produced by the lwt_ppx syntax extension. *)
   type Runtime_events.User.tag += T
   val span : t Runtime_events.User.t
   val emit : t -> unit
