.TH "Lazy" 3o source: 2019-01-25 OCamldoc "OCaml library"
.SH NAME
Lazy \- Deferred computations.
.SH Module
Module   Lazy
.SH Documentation
.sp
Module
.BI "Lazy"
 : 
.B sig  end

.sp
Deferred computations\&.

.sp

.sp
.sp
.I type 
.B 'a
.I t 
= 
.B 'a lazy_t

.sp
A value of type 
.B \&'a Lazy\&.t
is a deferred computation, called
a suspension, that has a result of type 
.B \&'a
\&.  The special
expression syntax 
.B lazy (expr)
makes a suspension of the
computation of 
.B expr
, without computing 
.B expr
itself yet\&.
"Forcing" the suspension will then compute 
.B expr
and return its
result\&.
.sp
Note: 
.B lazy_t
is the built\-in type constructor used by the compiler
for the 
.B lazy
keyword\&.  You should not use it directly\&.  Always use
.B Lazy\&.t
instead\&.
.sp
Note: 
.B Lazy\&.force
is not thread\-safe\&.  If you use this module in
a multi\-threaded program, you will need to add some locks\&.
.sp
Note: if the program is compiled with the 
.B \-rectypes
option,
ill\-founded recursive definitions of the form 
.B let rec x = lazy x
or 
.B let rec x = lazy(lazy(\&.\&.\&.(lazy x)))
are accepted by the type\-checker
and lead, when forced, to ill\-formed values that trigger infinite
loops in the garbage collector and other parts of the run\-time system\&.
Without the 
.B \-rectypes
option, such ill\-founded recursive definitions
are rejected by the type\-checker\&.

.sp

.I exception Undefined 

.sp

.sp

.I val force 
: 
.B 'a t -> 'a
.sp

.B force x
forces the suspension 
.B x
and returns its result\&.
If 
.B x
has already been forced, 
.B Lazy\&.force x
returns the
same value again without recomputing it\&.  If it raised an exception,
the same exception is raised again\&.
Raise 
.B Lazy\&.Undefined
if the forcing of 
.B x
tries to force 
.B x
itself
recursively\&.

.sp

.I val force_val 
: 
.B 'a t -> 'a
.sp

.B force_val x
forces the suspension 
.B x
and returns its
result\&.  If 
.B x
has already been forced, 
.B force_val x
returns the same value again without recomputing it\&.
Raise 
.B Lazy\&.Undefined
if the forcing of 
.B x
tries to force 
.B x
itself
recursively\&.
If the computation of 
.B x
raises an exception, it is unspecified
whether 
.B force_val x
raises the same exception or 
.B Lazy\&.Undefined
\&.

.sp

.I val from_fun 
: 
.B (unit -> 'a) -> 'a t
.sp

.B from_fun f
is the same as 
.B lazy (f ())
but slightly more efficient\&.
.sp

.B from_fun
should only be used if the function 
.B f
is already defined\&.
In particular it is always less efficient to write
.B from_fun (fun () \-> expr)
than 
.B lazy expr
\&.

.sp
.B "Since"
4.00.0

.sp

.I val from_val 
: 
.B 'a -> 'a t
.sp

.B from_val v
returns an already\-forced suspension of 
.B v
\&.
This is for special purposes only and should not be confused with
.B lazy (v)
\&.

.sp
.B "Since"
4.00.0

.sp

.I val is_val 
: 
.B 'a t -> bool
.sp

.B is_val x
returns 
.B true
if 
.B x
has already been forced and
did not raise an exception\&.

.sp
.B "Since"
4.00.0

.sp

.I val lazy_from_fun 
: 
.B (unit -> 'a) -> 'a t
.sp
.B "Deprecated."
synonym for 
.B from_fun
\&.

.sp

.I val lazy_from_val 
: 
.B 'a -> 'a t
.sp
.B "Deprecated."
synonym for 
.B from_val
\&.

.sp

.I val lazy_is_val 
: 
.B 'a t -> bool
.sp
.B "Deprecated."
synonym for 
.B is_val
\&.

.sp