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

NAME

6       Stdlib.Lazy - no description
7

Module

9       Module   Stdlib.Lazy
10

Documentation

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