mirror of
https://github.com/c-cube/moonpool.git
synced 2025-12-17 08:06:43 -05:00
5 lines
No EOL
12 KiB
HTML
5 lines
No EOL
12 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Lazy (ocaml.Stdlib.Lazy)</title><link rel="stylesheet" href="../../../_odoc-theme/odoc.css"/><meta charset="utf-8"/><meta name="generator" content="odoc 2.2.1"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../../../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – <a href="../../index.html">ocaml</a> » <a href="../index.html">Stdlib</a> » Lazy</nav><header class="odoc-preamble"><h1>Module <code><span>Stdlib.Lazy</span></code></h1><p>Deferred computations.</p></header><nav class="odoc-toc"><ul><li><a href="#iterators">Iterators</a></li><li><a href="#reasoning-on-already-forced-suspensions">Reasoning on already-forced suspensions</a></li><li><a href="#advanced">Advanced</a></li><li><a href="#deprecated">Deprecated</a></li></ul></nav><div class="odoc-content"><div class="odoc-spec"><div class="spec type anchored" id="type-t"><a href="#type-t" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a t</span></span><span> = <span><span class="type-var">'a</span> <a href="../../CamlinternalLazy/index.html#type-t">CamlinternalLazy.t</a></span></span></code></div><div class="spec-doc"><p>A value of type <code>'a Lazy.t</code> is a deferred computation, called a suspension, that has a result of type <code>'a</code>. The special expression syntax <code>lazy (expr)</code> makes a suspension of the computation of <code>expr</code>, without computing <code>expr</code> itself yet. "Forcing" the suspension will then compute <code>expr</code> and return its result. Matching a suspension with the special pattern syntax <code>lazy(pattern)</code> also computes the underlying expression and tries to bind it to <code>pattern</code>:</p><pre class="language-ocaml"><code>let lazy_option_map f x =
|
||
match x with
|
||
| lazy (Some x) -> Some (Lazy.force f x)
|
||
| _ -> None</code></pre><p>Note: If lazy patterns appear in multiple cases in a pattern-matching, lazy expressions may be forced even outside of the case ultimately selected by the pattern matching. In the example above, the suspension <code>x</code> is always computed.</p><p>Note: <code>lazy_t</code> is the built-in type constructor used by the compiler for the <code>lazy</code> keyword. You should not use it directly. Always use <code>Lazy.t</code> instead.</p><p>Note: <code>Lazy.force</code> is not thread-safe. If you use this module in a multi-threaded program, you will need to add some locks.</p><p>Note: if the program is compiled with the <code>-rectypes</code> option, ill-founded recursive definitions of the form <code>let rec x = lazy x</code> or <code>let rec x = lazy(lazy(...(lazy x)))</code> 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 <code>-rectypes</code> option, such ill-founded recursive definitions are rejected by the type-checker.</p></div></div><div class="odoc-spec"><div class="spec exception anchored" id="exception-Undefined"><a href="#exception-Undefined" class="anchor"></a><code><span><span class="keyword">exception</span> </span><span><span class="exception">Undefined</span></span></code></div></div><div class="odoc-spec"><div class="spec value external anchored" id="val-force"><a href="#val-force" class="anchor"></a><code><span><span class="keyword">val</span> force : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>force x</code> forces the suspension <code>x</code> and returns its result. If <code>x</code> has already been forced, <code>Lazy.force x</code> returns the same value again without recomputing it. If it raised an exception, the same exception is raised again.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <span class="value">Undefined</span> <p>if the forcing of <code>x</code> tries to force <code>x</code> itself recursively.</p></li></ul></div></div><h2 id="iterators"><a href="#iterators" class="anchor"></a>Iterators</h2><div class="odoc-spec"><div class="spec value anchored" id="val-map"><a href="#val-map" class="anchor"></a><code><span><span class="keyword">val</span> map : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span class="type-var">'b</span>)</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>map f x</code> returns a suspension that, when forced, forces <code>x</code> and applies <code>f</code> to its value.</p><p>It is equivalent to <code>lazy (f (Lazy.force x))</code>.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 4.13.0</li></ul></div></div><h2 id="reasoning-on-already-forced-suspensions"><a href="#reasoning-on-already-forced-suspensions" class="anchor"></a>Reasoning on already-forced suspensions</h2><div class="odoc-spec"><div class="spec value anchored" id="val-is_val"><a href="#val-is_val" class="anchor"></a><code><span><span class="keyword">val</span> is_val : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>is_val x</code> returns <code>true</code> if <code>x</code> has already been forced and did not raise an exception.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 4.00.0</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-from_val"><a href="#val-from_val" class="anchor"></a><code><span><span class="keyword">val</span> from_val : <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>from_val v</code> evaluates <code>v</code> first (as any function would) and returns an already-forced suspension of its result. It is the same as <code>let x = v in lazy x</code>, but uses dynamic tests to optimize suspension creation in some cases.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 4.00.0</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-map_val"><a href="#val-map_val" class="anchor"></a><code><span><span class="keyword">val</span> map_val : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span class="type-var">'b</span>)</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>map_val f x</code> applies <code>f</code> directly if <code>x</code> is already forced, otherwise it behaves as <code>map f x</code>.</p><p>When <code>x</code> is already forced, this behavior saves the construction of a suspension, but on the other hand it performs more work eagerly that may not be useful if you never force the function result.</p><p>If <code>f</code> raises an exception, it will be raised immediately when <code>is_val x</code>, or raised only when forcing the thunk otherwise.</p><p>If <code>map_val f x</code> does not raise an exception, then <code>is_val (map_val f x)</code> is equal to <code>is_val x</code>.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 4.13.0</li></ul></div></div><h2 id="advanced"><a href="#advanced" class="anchor"></a>Advanced</h2><p>The following definitions are for advanced uses only; they require familiary with the lazy compilation scheme to be used appropriately.</p><div class="odoc-spec"><div class="spec value anchored" id="val-from_fun"><a href="#val-from_fun" class="anchor"></a><code><span><span class="keyword">val</span> from_fun : <span><span>(<span>unit <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>from_fun f</code> is the same as <code>lazy (f ())</code> but slightly more efficient.</p><p>It should only be used if the function <code>f</code> is already defined. In particular it is always less efficient to write <code>from_fun (fun () -> expr)</code> than <code>lazy expr</code>.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 4.00.0</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-force_val"><a href="#val-force_val" class="anchor"></a><code><span><span class="keyword">val</span> force_val : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span class="type-var">'a</span></span></code></div><div class="spec-doc"><p><code>force_val x</code> forces the suspension <code>x</code> and returns its result. If <code>x</code> has already been forced, <code>force_val x</code> returns the same value again without recomputing it.</p><p>If the computation of <code>x</code> raises an exception, it is unspecified whether <code>force_val x</code> raises the same exception or <a href="#exception-Undefined"><code>Undefined</code></a>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <span class="value">Undefined</span> <p>if the forcing of <code>x</code> tries to force <code>x</code> itself recursively.</p></li></ul></div></div><h2 id="deprecated"><a href="#deprecated" class="anchor"></a>Deprecated</h2><div class="odoc-spec"><div class="spec value anchored" id="val-lazy_from_fun"><a href="#val-lazy_from_fun" class="anchor"></a><code><span><span class="keyword">val</span> lazy_from_fun : <span><span>(<span>unit <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> <p>synonym for <code>from_fun</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-lazy_from_val"><a href="#val-lazy_from_val" class="anchor"></a><code><span><span class="keyword">val</span> lazy_from_val : <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> <p>synonym for <code>from_val</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-lazy_is_val"><a href="#val-lazy_is_val" class="anchor"></a><code><span><span class="keyword">val</span> lazy_is_val : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> <p>synonym for <code>is_val</code>.</p></li></ul></div></div></div></body></html> |