mirror of
https://github.com/c-cube/moonpool.git
synced 2025-12-17 08:06:43 -05:00
2 lines
No EOL
11 KiB
HTML
2 lines
No EOL
11 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Weak (ocaml.Stdlib.Weak)</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> » Weak</nav><header class="odoc-preamble"><h1>Module <code><span>Stdlib.Weak</span></code></h1><p>Arrays of weak pointers and hash sets of weak pointers.</p></header><nav class="odoc-toc"><ul><li><a href="#low-level-functions">Low-level functions</a></li><li><a href="#weak-hash-sets">Weak hash sets</a></li></ul></nav><div class="odoc-content"><h2 id="low-level-functions"><a href="#low-level-functions" class="anchor"></a>Low-level functions</h2><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></code></div><div class="spec-doc"><p>The type of arrays of weak pointers (weak arrays). A weak pointer is a value that the garbage collector may erase whenever the value is not used any more (through normal pointers) by the program. Note that finalisation functions are run before the weak pointers are erased, because the finalisation functions can make values alive again (before 4.03 the finalisation functions were run after).</p><p>A weak pointer is said to be full if it points to a value, empty if the value was erased by the GC.</p><p>Notes:</p><ul><li>Integers are not allocated and cannot be stored in weak arrays.</li><li>Weak arrays cannot be marshaled using <a href="../index.html#val-output_value"><code>Stdlib.output_value</code></a> nor the functions of the <a href="../Marshal/index.html"><code>Marshal</code></a> module.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-create"><a href="#val-create" class="anchor"></a><code><span><span class="keyword">val</span> create : <span>int <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>Weak.create n</code> returns a new weak array of length <code>n</code>. All the pointers are initially empty.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <span class="value">Invalid_argument</span> <p>if <code>n</code> is not comprised between zero and <a href="../Obj/Ephemeron/index.html#val-max_ephe_length"><code>Obj.Ephemeron.max_ephe_length</code></a> (limits included).</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-length"><a href="#val-length" class="anchor"></a><code><span><span class="keyword">val</span> length : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>Weak.length ar</code> returns the length (number of elements) of <code>ar</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-set"><a href="#val-set" class="anchor"></a><code><span><span class="keyword">val</span> set : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> option</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Weak.set ar n (Some el)</code> sets the <code>n</code>th cell of <code>ar</code> to be a (full) pointer to <code>el</code>; <code>Weak.set ar n None</code> sets the <code>n</code>th cell of <code>ar</code> to empty.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <span class="value">Invalid_argument</span> <p>if <code>n</code> is not in the range 0 to <a href="#val-length"><code>Weak.length</code></a><code> a - 1</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-get"><a href="#val-get" class="anchor"></a><code><span><span class="keyword">val</span> get : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span><span class="type-var">'a</span> option</span></span></code></div><div class="spec-doc"><p><code>Weak.get ar n</code> returns None if the <code>n</code>th cell of <code>ar</code> is empty, <code>Some x</code> (where <code>x</code> is the value) if it is full.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <span class="value">Invalid_argument</span> <p>if <code>n</code> is not in the range 0 to <a href="#val-length"><code>Weak.length</code></a><code> a - 1</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-get_copy"><a href="#val-get_copy" class="anchor"></a><code><span><span class="keyword">val</span> get_copy : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span><span class="type-var">'a</span> option</span></span></code></div><div class="spec-doc"><p><code>Weak.get_copy ar n</code> returns None if the <code>n</code>th cell of <code>ar</code> is empty, <code>Some x</code> (where <code>x</code> is a (shallow) copy of the value) if it is full. In addition to pitfalls with mutable values, the interesting difference with <code>get</code> is that <code>get_copy</code> does not prevent the incremental GC from erasing the value in its current cycle (<code>get</code> may delay the erasure to the next GC cycle).</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <span class="value">Invalid_argument</span> <p>if <code>n</code> is not in the range 0 to <a href="#val-length"><code>Weak.length</code></a><code> a - 1</code>.</p><p>If the element is a custom block it is not copied.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-check"><a href="#val-check" class="anchor"></a><code><span><span class="keyword">val</span> check : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>Weak.check ar n</code> returns <code>true</code> if the <code>n</code>th cell of <code>ar</code> is full, <code>false</code> if it is empty. Note that even if <code>Weak.check ar n</code> returns <code>true</code>, a subsequent <a href="#val-get"><code>Weak.get</code></a><code> ar n</code> can return <code>None</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-fill"><a href="#val-fill" class="anchor"></a><code><span><span class="keyword">val</span> fill : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> option</span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Weak.fill ar ofs len el</code> sets to <code>el</code> all pointers of <code>ar</code> from <code>ofs</code> to <code>ofs + len - 1</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <span class="value">Invalid_argument</span> <p>if <code>ofs</code> and <code>len</code> do not designate a valid subarray of <code>a</code>.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-blit"><a href="#val-blit" class="anchor"></a><code><span><span class="keyword">val</span> blit : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span>int <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>int <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>Weak.blit ar1 off1 ar2 off2 len</code> copies <code>len</code> weak pointers from <code>ar1</code> (starting at <code>off1</code>) to <code>ar2</code> (starting at <code>off2</code>). It works correctly even if <code>ar1</code> and <code>ar2</code> are the same.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <span class="value">Invalid_argument</span> <p>if <code>off1</code> and <code>len</code> do not designate a valid subarray of <code>ar1</code>, or if <code>off2</code> and <code>len</code> do not designate a valid subarray of <code>ar2</code>.</p></li></ul></div></div><h2 id="weak-hash-sets"><a href="#weak-hash-sets" class="anchor"></a>Weak hash sets</h2><p>A weak hash set is a hashed set of values. Each value may magically disappear from the set when it is not used by the rest of the program any more. This is normally used to share data structures without inducing memory leaks. Weak hash sets are defined on values from a <a href="../Hashtbl/module-type-HashedType/index.html"><code>Hashtbl.HashedType</code></a> module; the <code>equal</code> relation and <code>hash</code> function are taken from that module. We will say that <code>v</code> is an instance of <code>x</code> if <code>equal x v</code> is <code>true</code>.</p><p>The <code>equal</code> relation must be able to work on a shallow copy of the values and give the same result as with the values themselves.</p><div class="odoc-spec"><div class="spec module-type anchored" id="module-type-S"><a href="#module-type-S" class="anchor"></a><code><span><span class="keyword">module</span> <span class="keyword">type</span> <a href="module-type-S/index.html">S</a></span><span> = <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p>The output signature of the functor <a href="Make/index.html"><code>Weak.Make</code></a>.</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Make"><a href="#module-Make" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Make/index.html">Make</a></span><span> (<a href="Make/argument-1-H/index.html">H</a> : <a href="../Hashtbl/module-type-HashedType/index.html">Hashtbl.HashedType</a>) : <a href="module-type-S/index.html">S</a> <span class="keyword">with</span> <span><span class="keyword">type</span> <a href="module-type-S/index.html#type-data">data</a> = <a href="Make/argument-1-H/index.html#type-t">H.t</a></span></span></code></div><div class="spec-doc"><p>Functor building an implementation of the weak hash set structure. <code>H.equal</code> can't be the physical equality, since only shallow copies of the elements in the set are given to it.</p></div></div></div></body></html> |