Up
# Module Deferred

### Signature

##
include Core_kernel.Std.Invariant.S1 with type
'a
t :=
'a
t

##
include Core_kernel.Std.Monad with type
'a
t :=
'a
t

##
include Monad_intf.S_without_syntax with type
'a
t :=
'a
t

##
include Monad_intf.Infix with type
'a
t :=
'a
t

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.

type
+'a
t
=
'a Deferred1.t

`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`

.

val
upon : 'a t -> ('a -> unit) -> unit

`upon t f`

will run `f v`

at some point after `t`

becomes determined with value
`v`

.

val
peek : 'a t -> 'a option

`peek t`

returns `Some v`

iff `t`

is determined with value `v`

.

val
value_exn : 'a t -> 'a

`value_exn t`

returns `v`

if `t`

is determined with value `v`

, and raises
otherwise.

val
is_determined : 'a t -> bool

`is_determined t`

returns `true`

iff `t`

is determined.

type
'a
t

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.

val
return : 'a -> 'a t

`return v`

returns the (trivial) computation that returns v.

module
Infix
: sig .. end

val
unit : unit t

`unit`

is a deferred that is always determined with value `()`

val
never : unit -> _ t

`never ()`

returns a deferred that never becomes determined

val
don't_wait_for : unit t -> unit

`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.

type
+'a
choice
=
'a Deferred1.choice

`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`

.

val
forever : 'state -> ('state -> 'state t) -> unit

`forever initial_state f`

repeatedly runs `f`

, supplying the state returned to the
next call to `f`

.