Sophie: ghc-7.4.2-4.mga5 i586

ghc-7.4.2-4.mga5.i586.rpm

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Foreign.StablePtr</title><link href="ocean.css" rel="stylesheet" type="text/css" title="Ocean" /><script src="haddock-util.js" type="text/javascript"></script><script type="text/javascript">//<![CDATA[
window.onload = function () {pageLoad();setSynopsis("mini_Foreign-StablePtr.html");};
//]]>
</script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="index.html">Contents</a></li><li><a href="doc-index.html">Index</a></li></ul><p class="caption">base-4.5.1.0: Basic libraries</p></div><div id="content"><div id="module-header"><table class="info"><tr><th>Portability</th><td>portable</td></tr><tr><th>Stability</th><td>provisional</td></tr><tr><th>Maintainer</th><td>ffi@haskell.org</td></tr><tr><th>Safe Haskell</th><td>Trustworthy</td></tr></table><p class="caption">Foreign.StablePtr</p></div><div id="table-of-contents"><p class="caption">Contents</p><ul><li><a href="#g:1">Stable references to Haskell values
</a><ul><li><a href="#g:2">The C-side interface
</a></li></ul></li></ul></div><div id="description"><p class="caption">Description</p><div class="doc"><p>This module is part of the Foreign Function Interface (FFI) and will usually
 be imported via the module <a href="Foreign.html">Foreign</a>.
</p></div></div><div id="synopsis"><p id="control.syn" class="caption expander" onclick="toggleSection('syn')">Synopsis</p><ul id="section.syn" class="hide" onclick="toggleSection('syn')"><li class="src short"><span class="keyword">data</span>  <a href="#t:StablePtr">StablePtr</a> a</li><li class="src short"><a href="#v:newStablePtr">newStablePtr</a> ::  a -&gt; <a href="System-IO.html#t:IO">IO</a> (<a href="Foreign-StablePtr.html#t:StablePtr">StablePtr</a> a)</li><li class="src short"><a href="#v:deRefStablePtr">deRefStablePtr</a> ::  <a href="Foreign-StablePtr.html#t:StablePtr">StablePtr</a> a -&gt; <a href="System-IO.html#t:IO">IO</a> a</li><li class="src short"><a href="#v:freeStablePtr">freeStablePtr</a> ::  <a href="Foreign-StablePtr.html#t:StablePtr">StablePtr</a> a -&gt; <a href="System-IO.html#t:IO">IO</a> <a href="../ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a></li><li class="src short"><a href="#v:castStablePtrToPtr">castStablePtrToPtr</a> ::  <a href="Foreign-StablePtr.html#t:StablePtr">StablePtr</a> a -&gt; <a href="Foreign-Ptr.html#t:Ptr">Ptr</a> <a href="../ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a></li><li class="src short"><a href="#v:castPtrToStablePtr">castPtrToStablePtr</a> ::  <a href="Foreign-Ptr.html#t:Ptr">Ptr</a> <a href="../ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a> -&gt; <a href="Foreign-StablePtr.html#t:StablePtr">StablePtr</a> a</li></ul></div><div id="interface"><h1 id="g:1">Stable references to Haskell values
</h1><div class="top"><p class="src"><span class="keyword">data</span>  <a name="t:StablePtr" class="def">StablePtr</a> a </p><div class="doc"><p>A <em>stable pointer</em> is a reference to a Haskell expression that is
guaranteed not to be affected by garbage collection, i.e., it will neither be
deallocated nor will the value of the stable pointer itself change during
garbage collection (ordinary references may be relocated during garbage
collection).  Consequently, stable pointers can be passed to foreign code,
which can treat it as an opaque reference to a Haskell value.
</p><p>A value of type <code>StablePtr a</code> is a stable pointer to a Haskell
expression of type <code>a</code>.
</p></div><div class="subs instances"><p id="control.i:StablePtr" class="caption collapser" onclick="toggleSection('i:StablePtr')">Instances</p><div id="section.i:StablePtr" class="show"><table><tr><td class="src"><a href="Data-Typeable-Internal.html#t:Typeable1">Typeable1</a> <a href="Foreign-StablePtr.html#t:StablePtr">StablePtr</a></td><td class="doc empty">&nbsp;</td></tr><tr><td class="src"><a href="Data-Eq.html#t:Eq">Eq</a> (<a href="Foreign-StablePtr.html#t:StablePtr">StablePtr</a> a)</td><td class="doc empty">&nbsp;</td></tr><tr><td class="src"><a href="Foreign-Storable.html#t:Storable">Storable</a> (<a href="Foreign-StablePtr.html#t:StablePtr">StablePtr</a> a)</td><td class="doc empty">&nbsp;</td></tr></table></div></div></div><div class="top"><p class="src"><a name="v:newStablePtr" class="def">newStablePtr</a> ::  a -&gt; <a href="System-IO.html#t:IO">IO</a> (<a href="Foreign-StablePtr.html#t:StablePtr">StablePtr</a> a)</p><div class="doc"><p>Create a stable pointer referring to the given Haskell value.
</p></div></div><div class="top"><p class="src"><a name="v:deRefStablePtr" class="def">deRefStablePtr</a> ::  <a href="Foreign-StablePtr.html#t:StablePtr">StablePtr</a> a -&gt; <a href="System-IO.html#t:IO">IO</a> a</p><div class="doc"><p>Obtain the Haskell value referenced by a stable pointer, i.e., the
 same value that was passed to the corresponding call to
 <code>makeStablePtr</code>.  If the argument to <code><a href="Foreign-StablePtr.html#v:deRefStablePtr">deRefStablePtr</a></code> has
 already been freed using <code><a href="Foreign-StablePtr.html#v:freeStablePtr">freeStablePtr</a></code>, the behaviour of
 <code><a href="Foreign-StablePtr.html#v:deRefStablePtr">deRefStablePtr</a></code> is undefined.
</p></div></div><div class="top"><p class="src"><a name="v:freeStablePtr" class="def">freeStablePtr</a> ::  <a href="Foreign-StablePtr.html#t:StablePtr">StablePtr</a> a -&gt; <a href="System-IO.html#t:IO">IO</a> <a href="../ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a></p><div class="doc"><p>Dissolve the association between the stable pointer and the Haskell
 value. Afterwards, if the stable pointer is passed to
 <code><a href="Foreign-StablePtr.html#v:deRefStablePtr">deRefStablePtr</a></code> or <code><a href="Foreign-StablePtr.html#v:freeStablePtr">freeStablePtr</a></code>, the behaviour is
 undefined.  However, the stable pointer may still be passed to
 <code><a href="Foreign-StablePtr.html#v:castStablePtrToPtr">castStablePtrToPtr</a></code>, but the <code><code><a href="Foreign-Ptr.html#t:Ptr">Ptr</a></code> ()</code> value returned
 by <code><a href="Foreign-StablePtr.html#v:castStablePtrToPtr">castStablePtrToPtr</a></code>, in this case, is undefined (in particular,
 it may be <code><a href="Foreign-Ptr.html#v:nullPtr">nullPtr</a></code>).  Nevertheless, the call
 to <code><a href="Foreign-StablePtr.html#v:castStablePtrToPtr">castStablePtrToPtr</a></code> is guaranteed not to diverge.
</p></div></div><div class="top"><p class="src"><a name="v:castStablePtrToPtr" class="def">castStablePtrToPtr</a> ::  <a href="Foreign-StablePtr.html#t:StablePtr">StablePtr</a> a -&gt; <a href="Foreign-Ptr.html#t:Ptr">Ptr</a> <a href="../ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a></p><div class="doc"><p>Coerce a stable pointer to an address. No guarantees are made about
 the resulting value, except that the original stable pointer can be
 recovered by <code><a href="Foreign-StablePtr.html#v:castPtrToStablePtr">castPtrToStablePtr</a></code>.  In particular, the address may not
 refer to an accessible memory location and any attempt to pass it to
 the member functions of the class <code><a href="Foreign-Storable.html#t:Storable">Storable</a></code> leads to
 undefined behaviour.
</p></div></div><div class="top"><p class="src"><a name="v:castPtrToStablePtr" class="def">castPtrToStablePtr</a> ::  <a href="Foreign-Ptr.html#t:Ptr">Ptr</a> <a href="../ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a> -&gt; <a href="Foreign-StablePtr.html#t:StablePtr">StablePtr</a> a</p><div class="doc"><p>The inverse of <code><a href="Foreign-StablePtr.html#v:castStablePtrToPtr">castStablePtrToPtr</a></code>, i.e., we have the identity
</p><pre> sp == castPtrToStablePtr (castStablePtrToPtr sp)
</pre><p>for any stable pointer <code>sp</code> on which <code><a href="Foreign-StablePtr.html#v:freeStablePtr">freeStablePtr</a></code> has
 not been executed yet.  Moreover, <code><a href="Foreign-StablePtr.html#v:castPtrToStablePtr">castPtrToStablePtr</a></code> may
 only be applied to pointers that have been produced by
 <code><a href="Foreign-StablePtr.html#v:castStablePtrToPtr">castStablePtrToPtr</a></code>.
</p></div></div><h2 id="g:2">The C-side interface
</h2><div class="doc"><p>The following definition is available to C programs inter-operating with
 Haskell code when including the header <code>HsFFI.h</code>.
</p><pre> typedef void *HsStablePtr;  
</pre><p>Note that no assumptions may be made about the values representing stable
 pointers.  In fact, they need not even be valid memory addresses.  The only
 guarantee provided is that if they are passed back to Haskell land, the
 function <code><a href="Foreign-StablePtr.html#v:deRefStablePtr">deRefStablePtr</a></code> will be able to reconstruct the
 Haskell value referred to by the stable pointer.
</p></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.11.0</p></div></body></html>