<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
<link rel="Start" href="index.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Ancient" rel="Chapter" href="Ancient.html"><link title="Shared memory mappings" rel="Section" href="#6_Sharedmemorymappings">
<link title="Additional information" rel="Section" href="#6_Additionalinformation">
<title>Ancient</title>
</head>
<body>
<div class="navbar"> <a href="index.html">Up</a>
</div>
<center><h1>Module <a href="type_Ancient.html">Ancient</a></h1></center>
<br>
<pre><span class="keyword">module</span> Ancient: <code class="code">sig</code> <a href="Ancient.html">..</a> <code class="code">end</code></pre>Mark objects as 'ancient' so they are taken out of the OCaml heap.<br>
<hr width="100%">
<pre><span id="TYPEancient"><span class="keyword">type</span> <code class="type">'a</code> ancient</span> </pre>
<pre><span id="VALmark"><span class="keyword">val</span> mark</span> : <code class="type">'a -> 'a <a href="Ancient.html#TYPEancient">ancient</a></code></pre><div class="info">
<code class="code">mark obj</code> copies <code class="code">obj</code> and all objects referenced
by <code class="code">obj</code> out of the OCaml heap. It returns the proxy
for <code class="code">obj</code>.
<p>
The copy of <code class="code">obj</code> accessed through the proxy MUST NOT be mutated.
<p>
If <code class="code">obj</code> represents a large object, then it is a good
idea to call <code class="code">Gc.compact</code> after marking to recover the
OCaml heap memory.<br>
</div>
<pre><span id="VALfollow"><span class="keyword">val</span> follow</span> : <code class="type">'a <a href="Ancient.html#TYPEancient">ancient</a> -> 'a</code></pre><pre><span id="VALdelete"><span class="keyword">val</span> delete</span> : <code class="type">'a <a href="Ancient.html#TYPEancient">ancient</a> -> unit</code></pre><pre><span id="VALis_ancient"><span class="keyword">val</span> is_ancient</span> : <code class="type">'a -> bool</code></pre><div class="info">
<code class="code">is_ancient ptr</code> returns true if <code class="code">ptr</code> is an object on the ancient
heap.<br>
</div>
<pre><span id="VALaddress_of"><span class="keyword">val</span> address_of</span> : <code class="type">'a -> nativeint</code></pre><div class="info">
<code class="code">address_of obj</code> returns the address of <code class="code">obj</code>, or <code class="code">0n</code> if <code class="code">obj</code>
is not a block.<br>
</div>
<br>
<span id="6_Sharedmemorymappings"><h6>Shared memory mappings</h6></span><br>
<pre><span id="TYPEmd"><span class="keyword">type</span> <code class="type"></code>md</span> </pre>
<div class="info">
Memory descriptor handle.<br>
</div>
<pre><span id="VALattach"><span class="keyword">val</span> attach</span> : <code class="type">Unix.file_descr -> nativeint -> <a href="Ancient.html#TYPEmd">md</a></code></pre><div class="info">
<code class="code">attach fd baseaddr</code> attaches to a new or existing file
which may contain shared objects.
<p>
Initially <code class="code">fd</code> should be a read/writable, zero-length file
(for example you could create this using <code class="code">Unix.openfile</code> and
passing the flags <code class="code">O_RDWR</code>, <code class="code">O_TRUNC</code>, <code class="code">O_CREAT</code>).
One or more objects can then be shared in this file
using <code class="code">Unix.share</code>.
<p>
For new files, <code class="code">baseaddr</code> specifies the virtual address to
map the file. Specifying <code class="code">Nativeint.zero</code> (<code class="code">0n</code>) here lets <code class="code">mmap(2)</code>
choose this, but on some platforms (notably Linux/AMD64)
<code class="code">mmap</code> chooses very unwisely, tending to map the memory
just before <code class="code">libc</code> with hardly any headroom to grow. If
you encounter this sort of problem (usually a segfault or
illegal instruction inside libc), then look at <code class="code">/proc/PID/maps</code>
and choose a more suitable address.
<p>
If the file was created previously, then the <code class="code">baseaddr</code> is
ignored. The underlying <code class="code">mmalloc</code> library will map the
file in at the same place as before.<br>
</div>
<pre><span id="VALdetach"><span class="keyword">val</span> detach</span> : <code class="type"><a href="Ancient.html#TYPEmd">md</a> -> unit</code></pre><div class="info">
<code class="code">detach md</code> detaches from an existing file, and closes it.<br>
</div>
<pre><span id="VALshare"><span class="keyword">val</span> share</span> : <code class="type"><a href="Ancient.html#TYPEmd">md</a> -> int -> 'a -> 'a <a href="Ancient.html#TYPEancient">ancient</a></code></pre><div class="info">
<code class="code">share md key obj</code> does the same as <a href="Ancient.html#VALmark"><code class="code">Ancient.mark</code></a> except
that instead of copying the object into local memory, it
writes it into memory which is backed by the attached file.
<p>
Shared mappings created this way may be shared between
other OCaml processes which can access the underlying
file. See <a href="Ancient.html#VALattach"><code class="code">Ancient.attach</code></a>, <a href="Ancient.html#VALdetach"><code class="code">Ancient.detach</code></a>.
<p>
More than one object can be stored in a file. The <code class="code">key</code>
parameter controls which object is written/overwritten by <code class="code">share</code>.
If you do not wish to use this feature, just pass <code class="code">0</code>
as the key.
<p>
Do not call <a href="Ancient.html#VALdelete"><code class="code">Ancient.delete</code></a> on a mapping created like this.
Instead, call <a href="Ancient.html#VALdetach"><code class="code">Ancient.detach</code></a> and, if necessary, delete the
underlying file.
<p>
Caution when sharing files/objects between processes:
The underlying <code class="code">mmalloc</code> library does not do any sort of
locking, so all calls to <code class="code">share</code> must ensure that they have
exclusive access to the underlying file while in progress.
(Other processes should not even call <a href="Ancient.html#VALget"><code class="code">Ancient.get</code></a> while
this is happening, but it seems safe to be just reading an
ancient object from the file).<br>
</div>
<pre><span id="VALget"><span class="keyword">val</span> get</span> : <code class="type"><a href="Ancient.html#TYPEmd">md</a> -> int -> 'a <a href="Ancient.html#TYPEancient">ancient</a></code></pre><div class="info">
<code class="code">get md key</code> returns the object indexed by <code class="code">key</code> in the
attached file.
<p>
For details of the <code class="code">key</code> parameter see <a href="Ancient.html#VALshare"><code class="code">Ancient.share</code></a>.
<p>
You need to annotate the returned object with the correct
type. As with the Marshal module, there is no type checking,
and setting the wrong type will likely cause a segfault
or undefined behaviour. Note that the returned object has
type <code class="code">sometype ancient</code>, not just <code class="code">sometype</code>.
<p>
<br>
</div>
<br>
<span id="6_Additionalinformation"><h6>Additional information</h6></span><br>
<br><code><span id="TYPEinfo"><span class="keyword">type</span> <code class="type"></code>info</span> = {</code><table class="typetable">
<tr>
<td align="left" valign="top" >
<code> </code></td>
<td align="left" valign="top" >
<code>i_size : <code class="type">int</code>;</code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >Allocated size, bytes.</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr></table>
}
<div class="info">
Extra information fields. See <a href="Ancient.html#VALmark_info"><code class="code">Ancient.mark_info</code></a> and
<a href="Ancient.html#VALshare_info"><code class="code">Ancient.share_info</code></a>.<br>
</div>
<pre><span id="VALmark_info"><span class="keyword">val</span> mark_info</span> : <code class="type">'a -> 'a <a href="Ancient.html#TYPEancient">ancient</a> * <a href="Ancient.html#TYPEinfo">info</a></code></pre><div class="info">
Same as <a href="Ancient.html#VALmark"><code class="code">Ancient.mark</code></a>, but also returns some extra information.<br>
</div>
<pre><span id="VALshare_info"><span class="keyword">val</span> share_info</span> : <code class="type"><a href="Ancient.html#TYPEmd">md</a> -> int -> 'a -> 'a <a href="Ancient.html#TYPEancient">ancient</a> * <a href="Ancient.html#TYPEinfo">info</a></code></pre><div class="info">
Same as <a href="Ancient.html#VALshare"><code class="code">Ancient.share</code></a>, but also returns some extra information.<br>
</div>
</body></html>
