Sophie: ghc-0:6.10.4-1mdv2010.0 i586

ghc-6.10.4-1mdv2010.0.i586.rpm

<!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.ForeignPtr</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-ForeignPtr.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.1.0.0: 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.ForeignPtr</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"
>Finalised data pointers
</A
></DT
><DD
><DL
><DT
><A HREF="#2"
>Basic operations
</A
></DT
><DT
><A HREF="#3"
>Low-level operations
</A
></DT
><DT
><A HREF="#4"
>Allocating managed memory
</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"
>The <TT
><A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
></TT
> type and operations.  This module is part of the
 Foreign Function Interface (FFI) and will usually be imported via
 the <A HREF="Foreign.html"
>Foreign</A
> module.
</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%3AForeignPtr"
>ForeignPtr</A
> a</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><SPAN CLASS="keyword"
>type</SPAN
> <A HREF="#t%3AFinalizerPtr"
>FinalizerPtr</A
> a = <A HREF="Foreign-Ptr.html#t%3AFunPtr"
>FunPtr</A
> (<A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="../ghc-prim/GHC-Unit.html#t%3A%28%29"
>()</A
>)</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><SPAN CLASS="keyword"
>type</SPAN
> <A HREF="#t%3AFinalizerEnvPtr"
>FinalizerEnvPtr</A
> env a = <A HREF="Foreign-Ptr.html#t%3AFunPtr"
>FunPtr</A
> (<A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> env -&gt; <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="../ghc-prim/GHC-Unit.html#t%3A%28%29"
>()</A
>)</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AnewForeignPtr"
>newForeignPtr</A
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AFinalizerPtr"
>FinalizerPtr</A
> a -&gt; <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a)</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AnewForeignPtr_"
>newForeignPtr_</A
> ::  <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a)</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AaddForeignPtrFinalizer"
>addForeignPtrFinalizer</A
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AFinalizerPtr"
>FinalizerPtr</A
> a -&gt; <A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="../ghc-prim/GHC-Unit.html#t%3A%28%29"
>()</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AnewForeignPtrEnv"
>newForeignPtrEnv</A
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AFinalizerEnvPtr"
>FinalizerEnvPtr</A
> env a -&gt; <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> env -&gt; <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a)</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AaddForeignPtrFinalizerEnv"
>addForeignPtrFinalizerEnv</A
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AFinalizerEnvPtr"
>FinalizerEnvPtr</A
> env a -&gt; <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> env -&gt; <A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="../ghc-prim/GHC-Unit.html#t%3A%28%29"
>()</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AwithForeignPtr"
>withForeignPtr</A
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a -&gt; (<A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> b) -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> b</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AfinalizeForeignPtr"
>finalizeForeignPtr</A
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="../ghc-prim/GHC-Unit.html#t%3A%28%29"
>()</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AunsafeForeignPtrToPtr"
>unsafeForeignPtrToPtr</A
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a -&gt; <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> a</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AtouchForeignPtr"
>touchForeignPtr</A
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="../ghc-prim/GHC-Unit.html#t%3A%28%29"
>()</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AcastForeignPtr"
>castForeignPtr</A
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a -&gt; <A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> b</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AmallocForeignPtr"
>mallocForeignPtr</A
> :: <A HREF="Foreign-Storable.html#t%3AStorable"
>Storable</A
> a =&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a)</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AmallocForeignPtrBytes"
>mallocForeignPtrBytes</A
> ::  <A HREF="../ghc-prim/GHC-Types.html#t%3AInt"
>Int</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a)</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AmallocForeignPtrArray"
>mallocForeignPtrArray</A
> :: <A HREF="Foreign-Storable.html#t%3AStorable"
>Storable</A
> a =&gt; <A HREF="../ghc-prim/GHC-Types.html#t%3AInt"
>Int</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a)</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AmallocForeignPtrArray0"
>mallocForeignPtrArray0</A
> :: <A HREF="Foreign-Storable.html#t%3AStorable"
>Storable</A
> a =&gt; <A HREF="../ghc-prim/GHC-Types.html#t%3AInt"
>Int</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</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"
>Finalised data pointers
</A
></A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><SPAN CLASS="keyword"
>data</SPAN
>  <A NAME="t:ForeignPtr"
><A NAME="t%3AForeignPtr"
></A
></A
><B
>ForeignPtr</B
> a </TD
></TR
><TR
><TD CLASS="body"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="ndoc"
><P
>The type <TT
><A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
></TT
> represents references to objects that are
 maintained in a foreign language, i.e., that are not part of the
 data structures usually managed by the Haskell storage manager.
 The essential difference between <TT
><A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
></TT
>s and vanilla memory
 references of type <TT
>Ptr a</TT
> is that the former may be associated
 with <EM
>finalizers</EM
>. A finalizer is a routine that is invoked when
 the Haskell storage manager detects that - within the Haskell heap
 and stack - there are no more references left that are pointing to
 the <TT
><A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
></TT
>.  Typically, the finalizer will, then, invoke
 routines in the foreign language that free the resources bound by
 the foreign object.
</P
><P
>The <TT
><A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
></TT
> is parameterised in the same way as <TT
><A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
></TT
>.  The
 type argument of <TT
><A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
></TT
> should normally be an instance of
 class <TT
><A HREF="Foreign-Storable.html#t%3AStorable"
>Storable</A
></TT
>.
</P
></TD
></TR
><TR
><TD CLASS="section4"
><IMG SRC="minus.gif" CLASS="coll" ONCLICK="toggle(this,'i:ForeignPtr')" ALT="show/hide"
> Instances</TD
></TR
><TR
><TD CLASS="body"
><DIV ID="i:ForeignPtr" 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-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="Data-Eq.html#t%3AEq"
>Eq</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a)</TD
></TR
><TR
><TD CLASS="decl"
><A HREF="Data-Typeable.html#t%3ATypeable"
>Typeable</A
> a =&gt; <A HREF="Data-Data.html#t%3AData"
>Data</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a)</TD
></TR
><TR
><TD CLASS="decl"
><A HREF="Data-Ord.html#t%3AOrd"
>Ord</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a)</TD
></TR
><TR
><TD CLASS="decl"
><A HREF="Text-Show.html#t%3AShow"
>Show</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a)</TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><SPAN CLASS="keyword"
>type</SPAN
> <A NAME="t:FinalizerPtr"
><A NAME="t%3AFinalizerPtr"
></A
></A
><B
>FinalizerPtr</B
> a = <A HREF="Foreign-Ptr.html#t%3AFunPtr"
>FunPtr</A
> (<A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="../ghc-prim/GHC-Unit.html#t%3A%28%29"
>()</A
>)</TD
></TR
><TR
><TD CLASS="doc"
>A Finalizer is represented as a pointer to a foreign function that, at
 finalisation time, gets as an argument a plain pointer variant of the
 foreign pointer that the finalizer is associated with.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><SPAN CLASS="keyword"
>type</SPAN
> <A NAME="t:FinalizerEnvPtr"
><A NAME="t%3AFinalizerEnvPtr"
></A
></A
><B
>FinalizerEnvPtr</B
> env a = <A HREF="Foreign-Ptr.html#t%3AFunPtr"
>FunPtr</A
> (<A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> env -&gt; <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="../ghc-prim/GHC-Unit.html#t%3A%28%29"
>()</A
>)</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section2"
><A NAME="2"
><A NAME="2"
>Basic operations
</A
></A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:newForeignPtr"
><A NAME="v%3AnewForeignPtr"
></A
></A
><B
>newForeignPtr</B
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AFinalizerPtr"
>FinalizerPtr</A
> a -&gt; <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a)</TD
></TR
><TR
><TD CLASS="doc"
>Turns a plain memory reference into a foreign pointer, and
 associates a finaliser with the reference.  The finaliser will be executed
 after the last reference to the foreign object is dropped.  Note that there
 is no guarantee on how soon the finaliser is executed after the last
 reference was dropped; this depends on the details of the Haskell storage
 manager.  Indeed, there is no guarantee that the finalizer is executed at
 all; a program may exit with finalizers outstanding.  (This is true
 of GHC, other implementations may give stronger guarantees).
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:newForeignPtr_"
><A NAME="v%3AnewForeignPtr_"
></A
></A
><B
>newForeignPtr_</B
> ::  <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a)</TD
></TR
><TR
><TD CLASS="doc"
>Turns a plain memory reference into a foreign pointer that may be
 associated with finalizers by using <TT
><A HREF="Foreign-ForeignPtr.html#v%3AaddForeignPtrFinalizer"
>addForeignPtrFinalizer</A
></TT
>.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:addForeignPtrFinalizer"
><A NAME="v%3AaddForeignPtrFinalizer"
></A
></A
><B
>addForeignPtrFinalizer</B
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AFinalizerPtr"
>FinalizerPtr</A
> a -&gt; <A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="../ghc-prim/GHC-Unit.html#t%3A%28%29"
>()</A
></TD
></TR
><TR
><TD CLASS="doc"
>This function adds a finalizer to the given foreign object.  The
 finalizer will run <EM
>before</EM
> all other finalizers for the same
 object which have already been registered.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:newForeignPtrEnv"
><A NAME="v%3AnewForeignPtrEnv"
></A
></A
><B
>newForeignPtrEnv</B
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AFinalizerEnvPtr"
>FinalizerEnvPtr</A
> env a -&gt; <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> env -&gt; <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a)</TD
></TR
><TR
><TD CLASS="doc"
>This variant of <TT
><A HREF="Foreign-ForeignPtr.html#v%3AnewForeignPtr"
>newForeignPtr</A
></TT
> adds a finalizer that expects an
 environment in addition to the finalized pointer.  The environment
 that will be passed to the finalizer is fixed by the second argument to
 <TT
><A HREF="Foreign-ForeignPtr.html#v%3AnewForeignPtrEnv"
>newForeignPtrEnv</A
></TT
>.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:addForeignPtrFinalizerEnv"
><A NAME="v%3AaddForeignPtrFinalizerEnv"
></A
></A
><B
>addForeignPtrFinalizerEnv</B
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AFinalizerEnvPtr"
>FinalizerEnvPtr</A
> env a -&gt; <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> env -&gt; <A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="../ghc-prim/GHC-Unit.html#t%3A%28%29"
>()</A
></TD
></TR
><TR
><TD CLASS="doc"
>like <TT
><A HREF="Foreign-ForeignPtr.html#v%3AaddForeignPtrFinalizerEnv"
>addForeignPtrFinalizerEnv</A
></TT
> but allows the finalizer to be
 passed an additional environment parameter to be passed to the
 finalizer.  The environment passed to the finalizer is fixed by the
 second argument to <TT
><A HREF="Foreign-ForeignPtr.html#v%3AaddForeignPtrFinalizerEnv"
>addForeignPtrFinalizerEnv</A
></TT
>
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:withForeignPtr"
><A NAME="v%3AwithForeignPtr"
></A
></A
><B
>withForeignPtr</B
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a -&gt; (<A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> b) -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> b</TD
></TR
><TR
><TD CLASS="doc"
><P
>This is a way to look at the pointer living inside a
 foreign object.  This function takes a function which is
 applied to that pointer. The resulting <TT
><A HREF="System-IO.html#t%3AIO"
>IO</A
></TT
> action is then
 executed. The foreign object is kept alive at least during
 the whole action, even if it is not used directly
 inside. Note that it is not safe to return the pointer from
 the action and use it after the action completes. All uses
 of the pointer should be inside the
 <TT
><A HREF="Foreign-ForeignPtr.html#v%3AwithForeignPtr"
>withForeignPtr</A
></TT
> bracket.  The reason for
 this unsafeness is the same as for
 <TT
><A HREF="Foreign-ForeignPtr.html#v%3AunsafeForeignPtrToPtr"
>unsafeForeignPtrToPtr</A
></TT
> below: the finalizer
 may run earlier than expected, because the compiler can only
 track usage of the <TT
><A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
></TT
> object, not
 a <TT
><A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
></TT
> object made from it.
</P
><P
>This function is normally used for marshalling data to
 or from the object pointed to by the
 <TT
><A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
></TT
>, using the operations from the
 <TT
><A HREF="Foreign-Storable.html#t%3AStorable"
>Storable</A
></TT
> class.
</P
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:finalizeForeignPtr"
><A NAME="v%3AfinalizeForeignPtr"
></A
></A
><B
>finalizeForeignPtr</B
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="../ghc-prim/GHC-Unit.html#t%3A%28%29"
>()</A
></TD
></TR
><TR
><TD CLASS="doc"
>Causes the finalizers associated with a foreign pointer to be run
 immediately.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section2"
><A NAME="3"
><A NAME="3"
>Low-level operations
</A
></A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:unsafeForeignPtrToPtr"
><A NAME="v%3AunsafeForeignPtrToPtr"
></A
></A
><B
>unsafeForeignPtrToPtr</B
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a -&gt; <A HREF="Foreign-Ptr.html#t%3APtr"
>Ptr</A
> a</TD
></TR
><TR
><TD CLASS="doc"
><P
>This function extracts the pointer component of a foreign
 pointer.  This is a potentially dangerous operations, as if the
 argument to <TT
><A HREF="Foreign-ForeignPtr.html#v%3AunsafeForeignPtrToPtr"
>unsafeForeignPtrToPtr</A
></TT
> is the last usage
 occurrence of the given foreign pointer, then its finalizer(s) will
 be run, which potentially invalidates the plain pointer just
 obtained.  Hence, <TT
><A HREF="Foreign-ForeignPtr.html#v%3AtouchForeignPtr"
>touchForeignPtr</A
></TT
> must be used
 wherever it has to be guaranteed that the pointer lives on - i.e.,
 has another usage occurrence.
</P
><P
>To avoid subtle coding errors, hand written marshalling code
 should preferably use Foreign.ForeignPtr.withForeignPtr rather
 than combinations of <TT
><A HREF="Foreign-ForeignPtr.html#v%3AunsafeForeignPtrToPtr"
>unsafeForeignPtrToPtr</A
></TT
> and
 <TT
><A HREF="Foreign-ForeignPtr.html#v%3AtouchForeignPtr"
>touchForeignPtr</A
></TT
>.  However, the later routines
 are occasionally preferred in tool generated marshalling code.
</P
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:touchForeignPtr"
><A NAME="v%3AtouchForeignPtr"
></A
></A
><B
>touchForeignPtr</B
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> <A HREF="../ghc-prim/GHC-Unit.html#t%3A%28%29"
>()</A
></TD
></TR
><TR
><TD CLASS="doc"
><P
>This function ensures that the foreign object in
 question is alive at the given place in the sequence of IO
 actions. In particular Foreign.ForeignPtr.withForeignPtr
 does a <TT
><A HREF="Foreign-ForeignPtr.html#v%3AtouchForeignPtr"
>touchForeignPtr</A
></TT
> after it
 executes the user action.
</P
><P
>Note that this function should not be used to express dependencies
 between finalizers on <TT
><A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
></TT
>s.  For example, if the finalizer
 for a <TT
><A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
></TT
> <TT
>F1</TT
> calls <TT
><A HREF="Foreign-ForeignPtr.html#v%3AtouchForeignPtr"
>touchForeignPtr</A
></TT
> on a second
 <TT
><A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
></TT
> <TT
>F2</TT
>, then the only guarantee is that the finalizer
 for <TT
>F2</TT
> is never started before the finalizer for <TT
>F1</TT
>.  They
 might be started together if for example both <TT
>F1</TT
> and <TT
>F2</TT
> are
 otherwise unreachable, and in that case the scheduler might end up
 running the finalizer for <TT
>F2</TT
> first.
</P
><P
>In general, it is not recommended to use finalizers on separate
 objects with ordering constraints between them.  To express the
 ordering robustly requires explicit synchronisation using <TT
>MVar</TT
>s
 between the finalizers, but even then the runtime sometimes runs
 multiple finalizers sequentially in a single thread (for
 performance reasons), so synchronisation between finalizers could
 result in artificial deadlock.  Another alternative is to use
 explicit reference counting.
</P
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:castForeignPtr"
><A NAME="v%3AcastForeignPtr"
></A
></A
><B
>castForeignPtr</B
> ::  <A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a -&gt; <A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> b</TD
></TR
><TR
><TD CLASS="doc"
>This function casts a <TT
><A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
></TT
>
 parameterised by one type into another type.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section2"
><A NAME="4"
><A NAME="4"
>Allocating managed memory
</A
></A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:mallocForeignPtr"
><A NAME="v%3AmallocForeignPtr"
></A
></A
><B
>mallocForeignPtr</B
> :: <A HREF="Foreign-Storable.html#t%3AStorable"
>Storable</A
> a =&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a)</TD
></TR
><TR
><TD CLASS="doc"
><P
>Allocate some memory and return a <TT
><A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
></TT
> to it.  The memory
 will be released automatically when the <TT
><A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
></TT
> is discarded.
</P
><P
><TT
><A HREF="Foreign-ForeignPtr.html#v%3AmallocForeignPtr"
>mallocForeignPtr</A
></TT
> is equivalent to
</P
><PRE
>    do { p &lt;- malloc; newForeignPtr finalizerFree p }
</PRE
><P
>although it may be implemented differently internally: you may not
 assume that the memory returned by <TT
><A HREF="Foreign-ForeignPtr.html#v%3AmallocForeignPtr"
>mallocForeignPtr</A
></TT
> has been
 allocated with Foreign.Marshal.Alloc.malloc.
</P
><P
>GHC notes: <TT
><A HREF="Foreign-ForeignPtr.html#v%3AmallocForeignPtr"
>mallocForeignPtr</A
></TT
> has a heavily optimised
 implementation in GHC.  It uses pinned memory in the garbage
 collected heap, so the <TT
><A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
></TT
> does not require a finalizer to
 free the memory.  Use of <TT
><A HREF="Foreign-ForeignPtr.html#v%3AmallocForeignPtr"
>mallocForeignPtr</A
></TT
> and associated
 functions is strongly recommended in preference to newForeignPtr
 with a finalizer.
</P
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:mallocForeignPtrBytes"
><A NAME="v%3AmallocForeignPtrBytes"
></A
></A
><B
>mallocForeignPtrBytes</B
> ::  <A HREF="../ghc-prim/GHC-Types.html#t%3AInt"
>Int</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a)</TD
></TR
><TR
><TD CLASS="doc"
>This function is similar to <TT
><A HREF="Foreign-ForeignPtr.html#v%3AmallocForeignPtr"
>mallocForeignPtr</A
></TT
>, except that the
 size of the memory required is given explicitly as a number of bytes.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:mallocForeignPtrArray"
><A NAME="v%3AmallocForeignPtrArray"
></A
></A
><B
>mallocForeignPtrArray</B
> :: <A HREF="Foreign-Storable.html#t%3AStorable"
>Storable</A
> a =&gt; <A HREF="../ghc-prim/GHC-Types.html#t%3AInt"
>Int</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a)</TD
></TR
><TR
><TD CLASS="doc"
>This function is similar to Foreign.Marshal.Array.mallocArray,
 but yields a memory area that has a finalizer attached that releases
 the memory area.  As with <TT
><A HREF="Foreign-ForeignPtr.html#v%3AmallocForeignPtr"
>mallocForeignPtr</A
></TT
>, it is not guaranteed that
 the block of memory was allocated by Foreign.Marshal.Alloc.malloc.
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:mallocForeignPtrArray0"
><A NAME="v%3AmallocForeignPtrArray0"
></A
></A
><B
>mallocForeignPtrArray0</B
> :: <A HREF="Foreign-Storable.html#t%3AStorable"
>Storable</A
> a =&gt; <A HREF="../ghc-prim/GHC-Types.html#t%3AInt"
>Int</A
> -&gt; <A HREF="System-IO.html#t%3AIO"
>IO</A
> (<A HREF="Foreign-ForeignPtr.html#t%3AForeignPtr"
>ForeignPtr</A
> a)</TD
></TR
><TR
><TD CLASS="doc"
>This function is similar to Foreign.Marshal.Array.mallocArray0,
 but yields a memory area that has a finalizer attached that releases
 the memory area.  As with <TT
><A HREF="Foreign-ForeignPtr.html#v%3AmallocForeignPtr"
>mallocForeignPtr</A
></TT
>, it is not guaranteed that
 the block of memory was allocated by Foreign.Marshal.Alloc.malloc.
</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.4.2</TD
></TR
></TABLE
></BODY
></HTML
>