1Lazy(3)                          OCaml library                         Lazy(3)
2
3
4

NAME

6       Lazy - Deferred computations.
7

Module

9       Module   Lazy
10

Documentation

12       Module Lazy
13        : sig end
14
15
16       Deferred computations.
17
18
19
20
21
22       type 'a t = 'a CamlinternalLazy.t
23
24
25       A  value  of type 'a Lazy.t is a deferred computation, called a suspen‐
26       sion, that has a result of type 'a . The special expression syntax lazy
27       (expr)  makes a suspension of the computation of expr , without comput‐
28       ing expr itself yet. "Forcing" the suspension will  then  compute  expr
29       and  return  its result. Matching a suspension with the special pattern
30       syntax lazy(pattern) also computes the underlying expression and  tries
31       to bind it to pattern :
32
33
34             let lazy_option_map f x =
35             match x with
36             | lazy (Some x) -> Some (Lazy.force f x)
37             | _ -> None
38
39
40       Note:  If lazy patterns appear in multiple cases in a pattern-matching,
41       lazy expressions may be forced even outside of the case ultimately  se‐
42       lected  by the pattern matching. In the example above, the suspension x
43       is always computed.
44
45       Note: lazy_t is the built-in type constructor used by the compiler  for
46       the  lazy  keyword.  You should not use it directly.  Always use Lazy.t
47       instead.
48
49       Note: Lazy.force is not concurrency-safe. If you use this  module  with
50       multiple  fibers, systhreads or domains, then you will need to add some
51       locks. The module however ensures  memory-safety,  and  hence,  concur‐
52       rently accessing this module will not lead to a crash but the behaviour
53       is unspecified.
54
55       Note: if the program is compiled with the -rectypes option, ill-founded
56       recursive  definitions  of  the  form let rec x = lazy x or let rec x =
57       lazy(lazy(...(lazy x))) are accepted by the type-checker and lead, when
58       forced, to ill-formed values that trigger infinite loops in the garbage
59       collector and other parts of the run-time system.   Without  the  -rec‐
60       types  option,  such  ill-founded recursive definitions are rejected by
61       the type-checker.
62
63
64
65       exception Undefined
66
67
68       Raised when forcing a suspension  concurrently  from  multiple  fibers,
69       systhreads or domains, or when the suspension tries to force itself re‐
70       cursively.
71
72
73
74       val force : 'a t -> 'a
75
76
77       force x forces the suspension x and returns its result. If  x  has  al‐
78       ready  been  forced,  Lazy.force x returns the same value again without
79       recomputing it.  If it raised  an  exception,  the  same  exception  is
80       raised again.
81
82
83       Raises Undefined (see Lazy.Undefined ).
84
85
86
87
88   Iterators
89       val map : ('a -> 'b) -> 'a t -> 'b t
90
91
92       map  f x returns a suspension that, when forced, forces x and applies f
93       to its value.
94
95       It is equivalent to lazy (f (Lazy.force x)) .
96
97
98       Since 4.13.0
99
100
101
102
103   Reasoning on already-forced suspensions
104       val is_val : 'a t -> bool
105
106
107       is_val x returns true if x has already been forced and did not raise an
108       exception.
109
110
111       Since 4.00.0
112
113
114
115       val from_val : 'a -> 'a t
116
117
118       from_val v evaluates v first (as any function would) and returns an al‐
119       ready-forced suspension of its result.  It is the same as let x = v  in
120       lazy x , but uses dynamic tests to optimize suspension creation in some
121       cases.
122
123
124       Since 4.00.0
125
126
127
128       val map_val : ('a -> 'b) -> 'a t -> 'b t
129
130
131       map_val f x applies f directly if x is already forced, otherwise it be‐
132       haves as map f x .
133
134       When  x  is  already  forced, this behavior saves the construction of a
135       suspension, but on the other hand it performs more  work  eagerly  that
136       may not be useful if you never force the function result.
137
138       If f raises an exception, it will be raised immediately when is_val x ,
139       or raised only when forcing the thunk otherwise.
140
141       If map_val f x does not raise an exception, then is_val (map_val  f  x)
142       is equal to is_val x .
143
144
145       Since 4.13.0
146
147
148
149
150   Advanced
151       The  following definitions are for advanced uses only; they require fa‐
152       miliary with the lazy compilation scheme to be used appropriately.
153
154       val from_fun : (unit -> 'a) -> 'a t
155
156
157       from_fun f is the same as lazy (f ()) but slightly more efficient.
158
159       It should only be used if the function f is already defined.   In  par‐
160       ticular  it is always less efficient to write from_fun (fun () -> expr)
161       than lazy expr .
162
163
164       Since 4.00.0
165
166
167
168       val force_val : 'a t -> 'a
169
170
171       force_val x forces the suspension x and returns its result.  If  x  has
172       already  been  forced, force_val x returns the same value again without
173       recomputing it.
174
175       If the computation of x raises an exception, it is unspecified  whether
176       force_val x raises the same exception or Lazy.Undefined .
177
178
179       Raises  Undefined  if  the  forcing of x tries to force x itself recur‐
180       sively.
181
182
183       Raises Undefined (see Lazy.Undefined ).
184
185
186
187
188
189OCamldoc                          2023-07-20                           Lazy(3)