add documentation; expose Runner.For_runner_implementors.Suspend_

src/runner.ml

@@ -34,4 +34,6 @@ let run_wait_block self (f : unit -> 'a) : 'a =
 module For_runner_implementors = struct
   let create ~size ~num_tasks ~shutdown ~run_async () : t =
     { size; num_tasks; shutdown; run_async }
+
+  module Suspend_ = Suspend_
 end

src/runner.mli

@@ -60,5 +60,17 @@ module For_runner_implementors : sig
     run_async:(task -> unit) ->
     unit ->
     t
-  (** Create a new runner. *)
+  (** Create a new runner.
+
+      {b NOTE}: the runner should support DLA and {!Suspend_} on OCaml 5.x,
+      so that {!Fork_join} and other 5.x features work properly. *)
+
+  module Suspend_ = Suspend_
+  [@@alert
+    unstable "this module is an implementation detail of moonpool for now"]
+  (** Suspensions.
+
+      This is only going to work on OCaml 5.x.
+
+      {b NOTE}: this is not stable for now. *)
 end

src/suspend_.mli

@@ -1,7 +1,7 @@
 (** (Private) suspending tasks using Effects.
 
    This module is an implementation detail of Moonpool and should
-   not be used outside of it. *)
+   not be used outside of it, except by experts to implement {!Runner}. *)
 
 type suspension = (unit, exn * Printexc.raw_backtrace) result -> unit
 (** A suspended computation *)
@@ -12,7 +12,24 @@ type suspension_handler = {
   handle: run:(with_handler:bool -> task -> unit) -> suspension -> unit;
 }
 [@@unboxed]
-(** The handler that knows what to do with the suspended computation *)
+(** The handler that knows what to do with the suspended computation.
+
+   The handler is given two things:
+
+   - the suspended computation (which can be resumed with a result
+     eventually);
+   - a [run] function that can be used to start tasks to perform some
+    computation.
+
+  This means that a fork-join primitive, for example, can use a single call
+  to {!suspend} to:
+    - suspend the caller until the fork-join is done
+    - use [run] to start all the tasks. Typically [run] is called multiple times,
+      which is where the "fork" part comes from. Each call to [run] potentially
+      runs in parallel with the other calls. The calls must coordinate so
+      that, once they are all done, the suspended caller is resumed with the
+      aggregated result of the computation.
+*)
 
 [@@@ifge 5.0]