Fix the documentation about a limitation of Miou.call

When we don't have enough domains (less than 3), it's impossible
to do a Miou.call into a Miou.call. Previously, an exception from
Random.int was raised. Now, we raise No_domain_available. We fixed the
documentation also to explain such situation.

Co-authored-by: Léo Andrès <[email protected]>

lib/miou.ml

@@ -1467,8 +1467,9 @@ let call ?orphans ?(give = []) fn =
   let cur = Domain.self () in
   let uid =
     let g = random () in
-    let l = List.filter (Fun.negate (Domain_uid.equal cur)) domains in
-    List.nth l (Random.State.int g (List.length l))
+    match List.filter (Fun.negate (Domain_uid.equal cur)) domains with
+    | [] -> raise No_domain_available
+    | lst -> List.nth lst (Random.State.int g (List.length lst))
   in
   let prm = Effect.perform (Spawn (Parallel uid, give, fn)) in
   Option.iter (Sequence.push prm) orphans;

lib/miou.mli

@@ -405,6 +405,15 @@
         Miou.await_exn prm
     ]}
 
+    The above rule also limits the use of {!val:call} if you only have (or want)
+    less than 3 domains. In fact, if you only have one domain, {!val:call}
+    cannot launch tasks in parallel. In the event that you only have 2 domains,
+    it is possible to launch a task in parallel from [dom0] but it is impossible
+    to launch a task in parallel from this [dom1].
+
+    In both cases and in such a situation, an exception is thrown:
+    {!exception:No_domain_available}.
+
     {4 Rule 7, suspension points are local to the domain.}
 
     A suspension point is local to the domain. This means that only the domain
@@ -715,7 +724,12 @@ val call : ?orphans:'a orphans -> ?give:Ownership.t list -> (unit -> 'a) -> 'a t
     {!val:parallel}.
 
     {b NOTE}: {!val:call} will never run a task on {i dom0} (the main domain).
-    Only the other domains can manage tasks in parallel. *)
+    Only the other domains can manage tasks in parallel.
+
+    @raise No_domain_available if no domain is available to execute the task in
+    parallel or if the function is executed by the only domain available in
+    parallel (it is impossible to assign a task to [dom0] from the other
+    domains). *)
 
 val parallel : ('a -> 'b) -> 'a list -> ('b, exn) result list
 (** [parallel fn lst] is the {i fork-join} model: it is a way of setting up and
@@ -1125,6 +1139,10 @@ val cancel : 'a t -> unit
 
 type handler = { handler: 'a 'b. ('a -> 'b) -> 'a -> 'b } [@@unboxed]
 
+exception No_domain_available
+(** An exception which can be raised by {!val:call} if no domain is available to
+    execute the task in parallel. *)
+
 val run :
      ?quanta:int
   -> ?events:(Domain.Uid.t -> events)

test/core/core.t

@@ -58,3 +58,4 @@
   World
   Hello
   World
+  $ ./t32.exe

test/core/dune

@@ -153,6 +153,11 @@
  (modules t31)
  (libraries miou))
 
+(executable
+ (name t32)
+ (modules t32)
+ (libraries miou))
+
 (cram
  (package miou)
  (deps
@@ -186,4 +191,5 @@
   t28.exe
   t29.exe
   t30.exe
-  t31.exe))
+  t31.exe
+  t32.exe))

test/core/t32.ml

@@ -0,0 +1,19 @@
+let program () =
+  let prm = Miou.call (Fun.const ()) in
+  Miou.await_exn prm
+
+let () =
+  try
+    Miou.run ~domains:0 program;
+    exit 1
+  with Miou.No_domain_available -> ()
+
+let program () =
+  let prm = Miou.call @@ fun () -> Miou.await_exn (Miou.call (Fun.const ())) in
+  Miou.await_exn prm
+
+let () =
+  try
+    Miou.run ~domains:1 program;
+    exit 1
+  with Miou.No_domain_available -> ()