From 925bf9a6d828d7548751f9a21892cad6209fc950 Mon Sep 17 00:00:00 2001 From: Gabriel Scherer Date: Fri, 16 Dec 2022 09:41:13 +0100 Subject: [PATCH 02/17] Merge pull request #11814 from gasche/clarify-DLS.new_key-doc clarify the doc of Domain.DLS.new_key (cherry picked from commit be210179503c4a82b72dd4762560e13c408d37b7) --- stdlib/domain.mli | 37 ++++++++++++++++++++++++++++++------- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/stdlib/domain.mli b/stdlib/domain.mli index 7763043aa5..2d79b3b0c3 100644 --- a/stdlib/domain.mli +++ b/stdlib/domain.mli @@ -96,15 +96,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. +, domain-local variables. - If [split_from_parent] is provided, spawning a domain will derive the - child value (for this key) from the parent value. + 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. - 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]. + 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 -- 2.41.0