clarify the doc of Domain.DLS.new_key

The discussion at
<https://discuss.ocaml.org/t/no-at-init-in-stdlib-domain/10954/4>
is the sign of a misunderstanding by Edwin Török, which suggests that
we need better documentation.

(improved with suggestions by Florian Angeletti)

1 files changed, 32 insertions, 9 deletions

diff --git a/stdlib/domain.mli b/stdlib/domain.mli
index e3c44af938..9f845bdd8e 100644
--- a/stdlib/domain.mli
+++ b/stdlib/domain.mli
@@ -90,15 +90,38 @@ module DLS : sig
 
     val new_key : ?split_from_parent:('a -> 'a) -> (unit -> 'a) -> 'a key
     (** [new_key f] returns a new key bound to initialiser [f] for accessing
-        domain-local variables.
-
-        If [split_from_parent] is provided, spawning a domain will derive the
-        child value (for this key) from the parent value.
-
-        Note that the [split_from_parent] call is computed in the parent
-        domain, and is always computed regardless of whether the child domain
-        will use it. If the splitting function is expensive or requires
-        client-side computation, consider using ['a Lazy.t key].
+,        domain-local variables.
+
+        If [split_from_parent] is not provided, the value for a new
+        domain will be computed on-demand by the new domain: the first
+        [get] call will call the initializer [f] and store that value.
+
+        If [split_from_parent] is provided, spawning a domain will
+        derive the child value (for this key) from the parent
+        value. This computation happens in the parent domain and it
+        always happens, regardless of whether the child domain will
+        use it.
+        If the splitting function is expensive or requires
+        child-side computation, consider using ['a Lazy.t key]:
+
+        {[
+        let init () = ...
+
+        let split_from_parent parent_value =
+          ... parent-side computation ...;
+          lazy (
+            ... child-side computation ...
+          )
+
+        let key = Domain.DLS.new_key ~split_from_parent init
+
+        let get () = Lazy.force (Domain.DLS.get key)
+        ]}
+
+        In this case a part of the computation happens on the child
+        domain; in particular, it can access [parent_value]
+        concurrently with the parent domain, which may require
+        explicit synchronization to avoid data races.
     *)
 
     val get : 'a key -> 'a