more docs, rename a function

src/core/fifo_pool.ml

@@ -128,7 +128,7 @@ let create ?(on_init_thread = default_thread_init_exit_)
     | None -> default_around_task_
   in
 
-  let num_domains = Domain_pool_.n_domains () in
+  let num_domains = Domain_pool_.max_number_of_domains () in
 
   (* number of threads to run *)
   let num_threads = Util_pool_.num_threads ?num_threads () in

src/core/moonpool.ml

@@ -3,7 +3,7 @@ open Types_
 exception Shutdown = Runner.Shutdown
 
 let start_thread_on_some_domain f x =
-  let did = Random.int (Domain_pool_.n_domains ()) in
+  let did = Random.int (Domain_pool_.max_number_of_domains ()) in
   Domain_pool_.run_on_and_wait did (fun () -> Thread.create f x)
 
 let run_async = Runner.run_async
@@ -39,5 +39,5 @@ module Private = struct
   module Domain_ = Domain_
   module Tracing_ = Tracing_
 
-  let num_domains = Domain_pool_.n_domains
+  let num_domains = Domain_pool_.max_number_of_domains
 end

src/core/util_pool_.ml

@@ -1,5 +1,5 @@
 let num_threads ?num_threads () : int =
-  let n_domains = Moonpool_dpool.n_domains () in
+  let n_domains = Moonpool_dpool.max_number_of_domains () in
 
   (* number of threads to run *)
   let num_threads =

src/core/ws_pool.ml

@@ -302,7 +302,7 @@ let create ?(on_init_thread = default_thread_init_exit_)
     | None -> AT_pair (ignore, fun _ _ -> ())
   in
 
-  let num_domains = Domain_pool_.n_domains () in
+  let num_domains = Domain_pool_.max_number_of_domains () in
   let num_threads = Util_pool_.num_threads ?num_threads () in
 
   (* make sure we don't bias towards the first domain(s) in {!D_pool_} *)

src/dpool/moonpool_dpool.ml

@@ -151,7 +151,7 @@ let () =
   ignore (Thread.create (fun () -> work_ 0 w) () : Thread.t);
   domains_.(0) <- Lock.create (Some w, None)
 
-let[@inline] n_domains () : int = Array.length domains_
+let[@inline] max_number_of_domains () : int = Array.length domains_
 
 let run_on (i : int) (f : unit -> unit) : unit =
   assert (i < Array.length domains_);

src/dpool/moonpool_dpool.mli

@@ -2,18 +2,31 @@
 
    These domains are shared between {b all} the pools in moonpool.
    The rationale is that we should not have more domains than cores, so
-   it's easier to pre-allocate exactly that many domains, and run more flexible
-   thread pools on top.
+   it's easier to reserve exactly that many domain slots, and run more flexible
+   thread pools on top (each domain being shared by potentially multiple threads
+   from multiple pools).
+
+   The pool should not contain actual domains if it's not in use, ie if no
+   runner is presently actively using one or more of the domain slots.
+
+   {b NOTE}: Interface is still experimental.
+
+   @since NEXT_RELEASE
 *)
 
 type domain = Domain_.t
 
-val n_domains : unit -> int
-(** Number of domains in the pool *)
+val max_number_of_domains : unit -> int
+(** Number of domains in the pool when all domains are active. *)
+
+(** {2 Low level interface for resouce handling}
+
+    Be very cautious with this interface, or resource leaks might occur. *)
 
 val run_on : int -> (unit -> unit) -> unit
 (** [run_on i f] runs [f()] on the domain with index [i].
-    Precondition: [0 <= i < n_domains()] *)
+    Precondition: [0 <= i < n_domains()]. The thread must call {!decr_on}
+    with [i] once it's done. *)
 
 val decr_on : int -> unit
 (** Signal that a thread is stopping on the domain with index [i]. *)