A value that will become determined asynchronously.
A deferred can be "undetermined" or "determined". A deferred that is undetermined may at some point become determined with value v, and will henceforth always be determined with value v.
sexp_of_t t f
returns a sexp of the deferred's value, if it is determined, or an
informative string otherwise.
This is just for display purposes. There is no t_of_sexp
.
upon t f
will run f v
at some point after t
becomes determined with value
v
.
peek t
returns Some v
iff t
is determined with value v
.
value_exn t
returns v
if t
is determined with value v
, and raises
otherwise.
is_determined t
returns true
iff t
is determined.
A monad is an abstraction of the concept of sequencing of computations. A value of type 'a monad represents a computation that returns a value of type 'a.
return v
returns the (trivial) computation that returns v.
unit
is a deferred that is always determined with value ()
never ()
returns a deferred that never becomes determined
don't_wait_for t
ignores t
. It is like Fn.ignore
, but is more constrained
because it requires a unit Deferred.t
.
Rather than ignore (t : _ t)
, do don't_wait_for (Deferred.ignore t)
.
We chose to give don't_wait_for
type unit t
rather than _ t
to catch errors
where a value is accidentally ignored.
choice
is used to produce an argument to enabled
or choose
. See below.
enabled [choice t1 f1; ... choice tn fn;]
returns a deferred d
that becomes
determined when any of the ti
become determined. The value of d
is a function f
that when called, for each ti
that is enabled, applies fi
to ti
, and returns a
list of the results. It is guaranteed that the list is in the same order as the
choices supplied to enabled
, but of course it may be shorter than the input list if
not all ti
are determined.
choose [ choice t1 f1
; ...
; choice tn fn
]
returns a deferred t
that becomes determined with value fi ai
after some ti
becomes determined with value ai
. It is guaranteed that choose
calls at most one
of the fi
s, the one that determines its result. There is no guarantee
that the ti
that becomes determined earliest in time will be the one whose value
determines the choose
. Nor is it guaranteed that the value in t
is the first value
(in place order) from choices
that is determined at the time t
is examined.
For example, in:
choose [ choice t1 (fun () -> `X1)
; choice t2 (fun () -> `X2)
]
>>> function
| `X1 -> e1
| `X2 -> e2
it may be the case that both t1
and t2
become determined, yet e2
actually runs.
It is guaranteed that if multiple choices are determined with no intervening
asynchrony, then the earliest choice in the list will become the value of the
choose
.
forever initial_state f
repeatedly runs f
, supplying the state returned to the
next call to f
.