<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <!--Rendered using the Haskell Html Library v0.2--> <HTML ><HEAD ><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8" ><TITLE >Foreign.StablePtr</TITLE ><LINK HREF="haddock.css" REL="stylesheet" TYPE="text/css" ><SCRIPT SRC="haddock-util.js" TYPE="text/javascript" ></SCRIPT ><SCRIPT TYPE="text/javascript" >window.onload = function () {setSynopsis("mini_Foreign-StablePtr.html")};</SCRIPT ></HEAD ><BODY ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="topbar" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD ><IMG SRC="haskell_icon.gif" WIDTH="16" HEIGHT="16" ALT=" " ></TD ><TD CLASS="title" >base-4.2.0.2: Basic libraries</TD ><TD CLASS="topbut" ><A HREF="index.html" >Contents</A ></TD ><TD CLASS="topbut" ><A HREF="doc-index.html" >Index</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="modulebar" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD ><FONT SIZE="6" >Foreign.StablePtr</FONT ></TD ><TD ALIGN="right" ><TABLE CLASS="narrow" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="infohead" >Portability</TD ><TD CLASS="infoval" >portable</TD ></TR ><TR ><TD CLASS="infohead" >Stability</TD ><TD CLASS="infoval" >provisional</TD ></TR ><TR ><TD CLASS="infohead" >Maintainer</TD ><TD CLASS="infoval" >ffi@haskell.org</TD ></TR ></TABLE ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="section4" ><B >Contents</B ></TD ></TR ><TR ><TD ><DL ><DT ><A HREF="#1" >Stable references to Haskell values </A ></DT ><DD ><DL ><DT ><A HREF="#2" >The C-side interface </A ></DT ></DL ></DD ></DL ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" >Description</TD ></TR ><TR ><TD CLASS="doc" >This module is part of the Foreign Function Interface (FFI) and will usually be imported via the module <A HREF="Foreign.html" >Foreign</A >. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" >Synopsis</TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="decl" ><SPAN CLASS="keyword" >data</SPAN > <A HREF="#t%3AStablePtr" >StablePtr</A > a</TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AnewStablePtr" >newStablePtr</A > :: a -> <A HREF="System-IO.html#t%3AIO" >IO</A > (<A HREF="Foreign-StablePtr.html#t%3AStablePtr" >StablePtr</A > a)</TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AdeRefStablePtr" >deRefStablePtr</A > :: <A HREF="Foreign-StablePtr.html#t%3AStablePtr" >StablePtr</A > a -> <A HREF="System-IO.html#t%3AIO" >IO</A > a</TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AfreeStablePtr" >freeStablePtr</A > :: <A HREF="Foreign-StablePtr.html#t%3AStablePtr" >StablePtr</A > a -> <A HREF="System-IO.html#t%3AIO" >IO</A > <A HREF="../ghc-prim-0.2.0.0/GHC-Unit.html#t%3A%28%29" >()</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AcastStablePtrToPtr" >castStablePtrToPtr</A > :: <A HREF="Foreign-StablePtr.html#t%3AStablePtr" >StablePtr</A > a -> <A HREF="Foreign-Ptr.html#t%3APtr" >Ptr</A > <A HREF="../ghc-prim-0.2.0.0/GHC-Unit.html#t%3A%28%29" >()</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AcastPtrToStablePtr" >castPtrToStablePtr</A > :: <A HREF="Foreign-Ptr.html#t%3APtr" >Ptr</A > <A HREF="../ghc-prim-0.2.0.0/GHC-Unit.html#t%3A%28%29" >()</A > -> <A HREF="Foreign-StablePtr.html#t%3AStablePtr" >StablePtr</A > a</TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="1" ><A NAME="1" >Stable references to Haskell values </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="decl" ><SPAN CLASS="keyword" >data</SPAN > <A NAME="t:StablePtr" ><A NAME="t%3AStablePtr" ></A ></A ><B >StablePtr</B > a </TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="ndoc" ><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 <TT >StablePtr a</TT > is a stable pointer to a Haskell expression of type <TT >a</TT >. </P ></TD ></TR ><TR ><TD CLASS="section4" ><IMG SRC="minus.gif" CLASS="coll" ONCLICK="toggle(this,'i:StablePtr')" ALT="show/hide" > Instances</TD ></TR ><TR ><TD CLASS="body" ><DIV ID="i:StablePtr" STYLE="display:block;" ><TABLE CLASS="vanilla" CELLSPACING="1" CELLPADDING="0" ><TR ><TD CLASS="decl" ><A HREF="Data-Typeable.html#t%3ATypeable1" >Typeable1</A > <A HREF="Foreign-StablePtr.html#t%3AStablePtr" >StablePtr</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Eq.html#t%3AEq" >Eq</A > (<A HREF="Foreign-StablePtr.html#t%3AStablePtr" >StablePtr</A > a)</TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Foreign-Storable.html#t%3AStorable" >Storable</A > (<A HREF="Foreign-StablePtr.html#t%3AStablePtr" >StablePtr</A > a)</TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="decl" ><A NAME="v:newStablePtr" ><A NAME="v%3AnewStablePtr" ></A ></A ><B >newStablePtr</B > :: a -> <A HREF="System-IO.html#t%3AIO" >IO</A > (<A HREF="Foreign-StablePtr.html#t%3AStablePtr" >StablePtr</A > a)</TD ></TR ><TR ><TD CLASS="doc" >Create a stable pointer referring to the given Haskell value. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="decl" ><A NAME="v:deRefStablePtr" ><A NAME="v%3AdeRefStablePtr" ></A ></A ><B >deRefStablePtr</B > :: <A HREF="Foreign-StablePtr.html#t%3AStablePtr" >StablePtr</A > a -> <A HREF="System-IO.html#t%3AIO" >IO</A > a</TD ></TR ><TR ><TD CLASS="doc" >Obtain the Haskell value referenced by a stable pointer, i.e., the same value that was passed to the corresponding call to makeStablePtr. If the argument to <TT ><A HREF="Foreign-StablePtr.html#v%3AdeRefStablePtr" >deRefStablePtr</A ></TT > has already been freed using <TT ><A HREF="Foreign-StablePtr.html#v%3AfreeStablePtr" >freeStablePtr</A ></TT >, the behaviour of <TT ><A HREF="Foreign-StablePtr.html#v%3AdeRefStablePtr" >deRefStablePtr</A ></TT > is undefined. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="decl" ><A NAME="v:freeStablePtr" ><A NAME="v%3AfreeStablePtr" ></A ></A ><B >freeStablePtr</B > :: <A HREF="Foreign-StablePtr.html#t%3AStablePtr" >StablePtr</A > a -> <A HREF="System-IO.html#t%3AIO" >IO</A > <A HREF="../ghc-prim-0.2.0.0/GHC-Unit.html#t%3A%28%29" >()</A ></TD ></TR ><TR ><TD CLASS="doc" >Dissolve the association between the stable pointer and the Haskell value. Afterwards, if the stable pointer is passed to <TT ><A HREF="Foreign-StablePtr.html#v%3AdeRefStablePtr" >deRefStablePtr</A ></TT > or <TT ><A HREF="Foreign-StablePtr.html#v%3AfreeStablePtr" >freeStablePtr</A ></TT >, the behaviour is undefined. However, the stable pointer may still be passed to <TT ><A HREF="Foreign-StablePtr.html#v%3AcastStablePtrToPtr" >castStablePtrToPtr</A ></TT >, but the <TT >Foreign.Ptr.Ptr ()</TT > value returned by <TT ><A HREF="Foreign-StablePtr.html#v%3AcastStablePtrToPtr" >castStablePtrToPtr</A ></TT >, in this case, is undefined (in particular, it may be Foreign.Ptr.nullPtr). Nevertheless, the call to <TT ><A HREF="Foreign-StablePtr.html#v%3AcastStablePtrToPtr" >castStablePtrToPtr</A ></TT > is guaranteed not to diverge. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="decl" ><A NAME="v:castStablePtrToPtr" ><A NAME="v%3AcastStablePtrToPtr" ></A ></A ><B >castStablePtrToPtr</B > :: <A HREF="Foreign-StablePtr.html#t%3AStablePtr" >StablePtr</A > a -> <A HREF="Foreign-Ptr.html#t%3APtr" >Ptr</A > <A HREF="../ghc-prim-0.2.0.0/GHC-Unit.html#t%3A%28%29" >()</A ></TD ></TR ><TR ><TD CLASS="doc" >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 <TT ><A HREF="Foreign-StablePtr.html#v%3AcastPtrToStablePtr" >castPtrToStablePtr</A ></TT >. 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 Foreign.Storable.Storable leads to undefined behaviour. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="decl" ><A NAME="v:castPtrToStablePtr" ><A NAME="v%3AcastPtrToStablePtr" ></A ></A ><B >castPtrToStablePtr</B > :: <A HREF="Foreign-Ptr.html#t%3APtr" >Ptr</A > <A HREF="../ghc-prim-0.2.0.0/GHC-Unit.html#t%3A%28%29" >()</A > -> <A HREF="Foreign-StablePtr.html#t%3AStablePtr" >StablePtr</A > a</TD ></TR ><TR ><TD CLASS="doc" ><P >The inverse of <TT ><A HREF="Foreign-StablePtr.html#v%3AcastStablePtrToPtr" >castStablePtrToPtr</A ></TT >, i.e., we have the identity </P ><PRE > sp == castPtrToStablePtr (castStablePtrToPtr sp) </PRE ><P >for any stable pointer <TT >sp</TT > on which <TT ><A HREF="Foreign-StablePtr.html#v%3AfreeStablePtr" >freeStablePtr</A ></TT > has not been executed yet. Moreover, <TT ><A HREF="Foreign-StablePtr.html#v%3AcastPtrToStablePtr" >castPtrToStablePtr</A ></TT > may only be applied to pointers that have been produced by <TT ><A HREF="Foreign-StablePtr.html#v%3AcastStablePtrToPtr" >castStablePtrToPtr</A ></TT >. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section2" ><A NAME="2" ><A NAME="2" >The C-side interface </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" ><P >The following definition is available to C programs inter-operating with Haskell code when including the header <TT >HsFFI.h</TT >. </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 <TT ><A HREF="Foreign-StablePtr.html#v%3AdeRefStablePtr" >deRefStablePtr</A ></TT > will be able to reconstruct the Haskell value referred to by the stable pointer. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="botbar" >Produced by <A HREF="http://www.haskell.org/haddock/" >Haddock</A > version 2.6.1</TD ></TR ></TABLE ></BODY ></HTML >