.TH "Domain.DLS" 3 2024-02-29 OCamldoc "OCaml library"
.SH NAME
Domain.DLS \- no description
.SH Module
Module   Domain.DLS
.SH Documentation
.sp
Module
.BI "DLS"
 : 
.B sig end

.sp

.sp

.sp
.sp

.PP
Domain\-local Storage
.PP
.I type 
.B 'a
.I key 

.sp
Type of a DLS key

.sp

.I val new_key 
: 
.B ?split_from_parent:('a -> 'a) -> (unit -> 'a) -> 'a key
.sp

.ft B
new_key f
.ft R
returns a new key bound to initialiser 
.ft B
f
.ft R
for accessing
,        domain\-local variables\&.
.sp
If 
.ft B
split_from_parent
.ft R
is not provided, the value for a new
domain will be computed on\-demand by the new domain: the first
.ft B
get
.ft R
call will call the initializer 
.ft B
f
.ft R
and store that value\&.
.sp
If 
.ft B
split_from_parent
.ft R
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 
.ft B
\&'a Lazy\&.t key
.ft R
:
.sp

.EX
.ft B
.br
\&        let init () = \&.\&.\&.
.br
\&
.br
\&        let split_from_parent parent_value =
.br
\&          \&.\&.\&. parent\-side computation \&.\&.\&.;
.br
\&          lazy (
.br
\&            \&.\&.\&. child\-side computation \&.\&.\&.
.br
\&          )
.br
\&
.br
\&        let key = Domain\&.DLS\&.new_key ~split_from_parent init
.br
\&
.br
\&        let get () = Lazy\&.force (Domain\&.DLS\&.get key)
.br
\&        
.ft R
.EE
.sp
In this case a part of the computation happens on the child
domain; in particular, it can access 
.ft B
parent_value
.ft R
concurrently with the parent domain, which may require
explicit synchronization to avoid data races\&.

.sp

.I val get 
: 
.B 'a key -> 'a
.sp

.ft B
get k
.ft R
returns 
.ft B
v
.ft R
if a value 
.ft B
v
.ft R
is associated to the key 
.ft B
k
.ft R
on
the calling domain\&'s domain\-local state\&. Sets 
.ft B
k
.ft R
\&'s value with its
initialiser and returns it otherwise\&.

.sp

.I val set 
: 
.B 'a key -> 'a -> unit
.sp

.ft B
set k v
.ft R
updates the calling domain\&'s domain\-local state to associate
the key 
.ft B
k
.ft R
with value 
.ft B
v
.ft R
\&. It overwrites any previous values associated
to 
.ft B
k
.ft R
, which cannot be restored later\&.

.sp