fix Haskell 98 reference
[haskell-report.git] / report / lib-foreignptr.verb
1 \section{@Foreign.ForeignPtr@}
2 \label{sec:ForeignPtr}
3
4 The type @ForeignPtr@ represents references to objects that are
5 maintained in a foreign language, i.e., objects that are not part of the data
6 structures usually managed by the Haskell storage manager.  The type
7 @ForeignPtr@ is parameterised in the same way as @Ptr@ (cf.\ 
8 Section~\ref{sec:Ptr}), but in contrast to vanilla memory references of type
9 @Ptr@, @ForeignPtr@s may be associated with finalizers.  A finalizer
10 is a routine that is invoked when the Haskell storage manager detects
11 that---within the Haskell heap and stack---there are no more references left
12 that are pointing to the @ForeignPtr@.  Typically, the finalizer will
13 free the resources bound by the foreign object.  Finalizers are generally
14 implemented in the foreign language\footnote{Finalizers in Haskell cannot be
15   safely realised without requiring support for
16   concurrency~\cite{boehm:finalizers}.} and have either of the following two
17 Haskell types:
18 %
19 \bprog
20 @
21 type FinalizerPtr        a = FunPtr (           Ptr a -> IO ())
22 type FinalizerEnvPtr env a = FunPtr (Ptr env -> Ptr a -> IO ())
23 @
24 \eprog
25 %
26 A foreign finalizer is represented as a pointer to a C function of type
27 @Ptr a -> IO ()@ or a C function of type @Ptr env -> Ptr a -> IO ()@, where @Ptr env@ represents an optional environment passed to the
28 finalizer on invocation.  That is, a foreign finalizer attached to a finalized
29 pointer @ForeignPtr a@ gets the finalized pointer in the form of a raw
30 pointer of type @Ptr a@ as an argument when it is invoked.  In addition,
31 a foreign finalizer of type @FinalizerEnvPtr env a@ also gets an
32 environment pointer of type @Ptr env@.  There is no guarantee on how soon
33 the finalizer is executed after the last reference to the associated foreign
34 pointer was dropped; this depends on the details of the Haskell storage
35 manager.  The only guarantee is that the finalizer runs before the program
36 terminates.  Whether a finalizer may call back into the Haskell system is
37 system dependent.  Portable code may not rely on such callbacks.
38
39 Foreign finalizers that expect an environment are a means to model closures in
40 languages that do not support them natively, such as C.  They recover part of
41 the convenience lost by requiring finalizers to be defined in the foreign
42 languages rather than in Haskell.
43
44 The data type @ForeignPtr@ and associated operations have the following
45 signature and purpose:
46 %
47 \begin{codedesc}
48 \item[data ForeignPtr a] A value of type @ForeignPtr a@ represents a
49   pointer to an object, or an array of objects, which may be marshalled to or
50   from Haskell values of type @a@.  The type @a@ will normally be an
51   instance of class @Storable@ (see Section~\ref{sec:Storable}), which
52   provides the marshalling operations.
53   
54   Instances for the classes @Eq@, @Ord@, and @Show@ are
55   provided.  Equality and ordering of two foreign pointers are the same as for
56   the plain pointers obtained with @unsafeForeignPtrToPtr@ from those
57   foreign pointers.
58   
59 \item[newForeignPtr\_ ::\ Ptr a -> IO (ForeignPtr a)]
60   Turn a plain memory reference into a foreign pointer that may be associated
61   with finalizers by using @addForeignPtrFinalizer@.
62   
63 \item[newForeignPtr ::\ FinalizerPtr a -> Ptr a -> IO (ForeignPtr a)] This is
64   a convenience function that turns a plain memory reference into a foreign
65   pointer and immediately adds a finalizer.  It is defined as
66   %
67 \bprog
68 @
69 newForeignPtr finalizer ptr = 
70   do
71     fp <- newForeignPtr_ ptr
72     addForeignPtrFinalizer finalizer fp
73     return fp
74 @
75 \eprog
76    
77 \item[newForeignPtrEnv ::\ FinalizerEnvPtr env a -> Ptr env -> Ptr a -> IO
78   (ForeignPtr a)] This variant of @newForeignPtr@ adds a finalizer that
79   expects an environment in addition to the finalized pointer.  The
80   environment that will be passed to the finalizer is fixed by the second
81   argument to @newForeignPtrEnv@.
82
83 \item[addForeignPtrFinalizer ::\ FinalizerPtr a -> ForeignPtr a -> IO
84   ()] Add a finalizer to the given foreign pointer.  All finalizers
85   associated with a single foreign pointer are executed in the opposite order
86   of their addition---i.e., the finalizer added last will be executed first.
87   
88 \item[addForeignPtrFinalizerEnv ::\ FinalizerEnvPtr env a -> Ptr env ->
89   ForeignPtr a]
90 \item[~~~~~~~~~~~~~~~~~~~~~~~~~~-> IO ()]\combineitems Add a finalizer that
91   expects an environment to an existing foreign pointer.
92
93 \item[mallocForeignPtr ::\ Storable a => IO (ForeignPtr a)] Allocate a block
94   of memory that is sufficient to hold values of type @a@.  The size of
95   the memory area is determined by the function @Storable.sizeOf@
96   (Section~\ref{sec:Storable}).  This corresponds to
97   @Foreign.Marshal.Alloc.malloc@ (Section~\ref{sec:MarshalAlloc}), but
98   automatically attaches a finalizer that frees the block of memory as soon as
99   all references to that block of of memory have been dropped.  It is
100   \emph{not} guaranteed that the block of memory was allocated by
101   @Foreign.Marshal.Alloc.malloc@; so, @Foreign.Marshal.Alloc.realloc@ must not be
102   applied to the resulting pointer.
103
104 \item[mallocForeignPtrBytes ::\ Int -> IO (ForeignPtr a)] Allocate a block of
105   memory of the given number of bytes with a finalizer attached that frees the
106   block of memory as soon as all references to that block of memory have
107   been dropped.  As for @mallocForeignPtr@, @Foreign.Marshal.Alloc.realloc@
108   must not be applied to the resulting pointer.
109
110 \item[mallocForeignPtrArray~ ::\ Storable a => Int -> IO (ForeignPtr a)]
111 \item[mallocForeignPtrArray0 ::\ Storable a => Int -> IO (ForeignPtr a)]%
112   \combineitems These functions correspond to @Foreign.Marshal.Array@'s
113   @mallocArray@ and @mallocArray0@, respectively, but yield a memory
114   area that has a finalizer attached that releases the memory area.  As with
115   the previous two functions, it is not guaranteed that the block of memory
116   was allocated by @Foreign.Marshal.Alloc.malloc@.
117   
118 \item[withForeignPtr ::\ ForeignPtr a -> (Ptr a -> IO b) -> IO b]
119   This is a way to obtain the pointer living inside a foreign pointer. This
120   function takes a function which is applied to that pointer. The resulting
121   @IO@ action is then executed. The foreign pointer is kept alive at least
122   during the whole action, even if it is not used directly inside. Note that
123   it is not safe to return the pointer from the action and use it after the
124   action completes.  All uses of the pointer should be inside the
125   @withForeignPtr@ bracket.
126
127   More precisely, the foreign pointer may be finalized after
128   @withForeignPtr@ is finished if the first argument was the last
129   occurrence of that foreign pointer.  Finalisation of the foreign pointer
130   might render the pointer that is passed to the function useless.
131   Consequently, this pointer cannot be used safely anymore after the
132   @withForeignPtr@ is finished, unless the function
133   @touchForeignPtr@ is used to explicitly keep the foreign pointer alive.
134   
135   This function is normally used for marshalling data to or from the object
136   pointed to by the @ForeignPtr@, using the operations from the
137   @Storable@ class.
138
139 \item[unsafeForeignPtrToPtr ::\ ForeignPtr a -> Ptr a]
140   Extract the pointer component of a foreign pointer. This is a potentially
141   dangerous operation.  If the argument to @unsafeForeignPtrToPtr@ is the
142   last usage occurrence of the given foreign pointer, then its finalizer(s)
143   will be run, which potentially invalidates the plain pointer just obtained.
144   Hence, @touchForeignPtr@ must be used wherever it has to be guaranteed
145   that the pointer lives on---i.e., has another usage occurrence.
146   
147   It should be noticed that this function does not need to be monadic when
148   used in combination with @touchForeignPtr@.  Until the
149   @unsafeForeignPtrToPtr@ is executed, the thunk representing the
150   suspended call keeps the foreign pointer alive.  Afterwards, the
151   @touchForeignPtr@ keeps the pointer alive.
152   
153   To avoid subtle coding errors, hand written marshalling code should
154   preferably use the function @withForeignPtr@ rather than
155   @unsafeForeignPtrToPtr@ and @touchForeignPtr@. However, the later
156   routines are occasionally preferred in tool-generated marshalling code.
157   
158 \item[touchForeignPtr ::\ ForeignPtr a -> IO ()] Ensure that the foreign
159   pointer in question is alive at the given place in the sequence of @IO@
160   actions. In particular, @withForeignPtr@ does a @touchForeignPtr@
161   after it executes the user action.
162   
163   This function can be used to express liveness dependencies between
164   @ForeignPtr@s: For example, if the finalizer for one @ForeignPtr@
165   touches a second @ForeignPtr@, then it is ensured that the second
166   @ForeignPtr@ will stay alive at least as long as the first. This can be
167   useful when you want to manipulate interior pointers to a foreign structure:
168   You can use @touchForeignPtr@ to express the requirement that the
169   exterior pointer must not be finalized until the interior pointer is no
170   longer referenced.
171     
172 \item[castForeignPtr ::\ ForeignPtr a -> ForeignPtr b] Cast a
173   @ForeignPtr@ parameterised by one type into another type.
174 \end{codedesc}