remove instances for types/classes that are not part of Haskell
[haskell-report.git] / report / libs / Foreign-ForeignPtr.tex
1 \haddockmoduleheading{Foreign.ForeignPtr}
2 \label{module:Foreign.ForeignPtr}
3 \haddockbeginheader
4 {\haddockverb\begin{verbatim}
5 module Foreign.ForeignPtr (
6 ForeignPtr, FinalizerPtr, FinalizerEnvPtr, newForeignPtr,
7 newForeignPtr_, addForeignPtrFinalizer, newForeignPtrEnv,
8 addForeignPtrFinalizerEnv, withForeignPtr, unsafeForeignPtrToPtr,
9 touchForeignPtr, castForeignPtr, mallocForeignPtr,
10 mallocForeignPtrBytes, mallocForeignPtrArray, mallocForeignPtrArray0
11 ) where\end{verbatim}}
12 \haddockendheader
13
14 \section{Finalised data pointers
15 }
16 \begin{haddockdesc}
17 \item[\begin{tabular}{@{}l}
18 data\ ForeignPtr\ a
19 \end{tabular}]\haddockbegindoc
20 The type \haddockid{ForeignPtr} represents references to objects that are
21 maintained in a foreign language, i.e., that are not part of the
22 data structures usually managed by the Haskell storage manager.
23 The essential difference between \haddockid{ForeignPtr}s and vanilla memory
24 references of type \haddocktt{Ptr\ a} is that the former may be associated
25 with \emph{finalizers}. A finalizer is a routine that is invoked when
26 the Haskell storage manager detects that - within the Haskell heap
27 and stack - there are no more references left that are pointing to
28 the \haddockid{ForeignPtr}. Typically, the finalizer will, then, invoke
29 routines in the foreign language that free the resources bound by
30 the foreign object.
31 \par
32 The \haddockid{ForeignPtr} is parameterised in the same way as \haddockid{Ptr}. The
33 type argument of \haddockid{ForeignPtr} should normally be an instance of
34 class \haddockid{Storable}.
35 \par
36
37 \end{haddockdesc}
38 \begin{haddockdesc}
39 \item[\begin{tabular}{@{}l}
40 instance\ Eq\ (ForeignPtr\ a)\\instance\ Ord\ (ForeignPtr\ a)\\instance\ Show\ (ForeignPtr\ a)
41 \end{tabular}]
42 \end{haddockdesc}
43 \begin{haddockdesc}
44 \item[\begin{tabular}{@{}l}
45 type\ FinalizerPtr\ a\ =\ FunPtr\ (Ptr\ a\ ->\ IO\ ())
46 \end{tabular}]\haddockbegindoc
47 A Finalizer is represented as a pointer to a foreign function that, at
48 finalisation time, gets as an argument a plain pointer variant of the
49 foreign pointer that the finalizer is associated with.
50 \par
51
52 \end{haddockdesc}
53 \begin{haddockdesc}
54 \item[\begin{tabular}{@{}l}
55 type\ FinalizerEnvPtr\ env\ a\ =\ FunPtr\ (Ptr\ env\ ->\ Ptr\ a\ ->\ IO\ ())
56 \end{tabular}]
57 \end{haddockdesc}
58 \subsection{Basic operations
59 }
60 \begin{haddockdesc}
61 \item[\begin{tabular}{@{}l}
62 newForeignPtr\ ::\ FinalizerPtr\ a\ ->\ Ptr\ a\ ->\ IO\ (ForeignPtr\ a)
63 \end{tabular}]\haddockbegindoc
64 Turns a plain memory reference into a foreign pointer, and
65 associates a finaliser with the reference. The finaliser will be
66 executed after the last reference to the foreign object is dropped.
67 There is no guarantee of promptness, however the finalizer will be
68 executed before the program exits.
69 \par
70
71 \end{haddockdesc}
72 \begin{haddockdesc}
73 \item[\begin{tabular}{@{}l}
74 newForeignPtr{\char '137}\ ::\ Ptr\ a\ ->\ IO\ (ForeignPtr\ a)
75 \end{tabular}]\haddockbegindoc
76 Turns a plain memory reference into a foreign pointer that may be
77 associated with finalizers by using \haddockid{addForeignPtrFinalizer}.
78 \par
79
80 \end{haddockdesc}
81 \begin{haddockdesc}
82 \item[\begin{tabular}{@{}l}
83 addForeignPtrFinalizer\ ::\ FinalizerPtr\ a\ ->\ ForeignPtr\ a\ ->\ IO\ ()
84 \end{tabular}]\haddockbegindoc
85 This function adds a finalizer to the given foreign object. The
86 finalizer will run \emph{before} all other finalizers for the same
87 object which have already been registered.
88 \par
89
90 \end{haddockdesc}
91 \begin{haddockdesc}
92 \item[\begin{tabular}{@{}l}
93 newForeignPtrEnv\ ::\ FinalizerEnvPtr\ env\ a\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ Ptr\ env\ ->\ Ptr\ a\ ->\ IO\ (ForeignPtr\ a)
94 \end{tabular}]\haddockbegindoc
95 This variant of \haddockid{newForeignPtr} adds a finalizer that expects an
96 environment in addition to the finalized pointer. The environment
97 that will be passed to the finalizer is fixed by the second argument to
98 \haddockid{newForeignPtrEnv}.
99 \par
100
101 \end{haddockdesc}
102 \begin{haddockdesc}
103 \item[\begin{tabular}{@{}l}
104 addForeignPtrFinalizerEnv\ ::\ FinalizerEnvPtr\ env\ a\\\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ->\ Ptr\ env\ ->\ ForeignPtr\ a\ ->\ IO\ ()
105 \end{tabular}]\haddockbegindoc
106 like \haddockid{addForeignPtrFinalizerEnv} but allows the finalizer to be
107 passed an additional environment parameter to be passed to the
108 finalizer. The environment passed to the finalizer is fixed by the
109 second argument to \haddockid{addForeignPtrFinalizerEnv}
110 \par
111
112 \end{haddockdesc}
113 \begin{haddockdesc}
114 \item[\begin{tabular}{@{}l}
115 withForeignPtr\ ::\ ForeignPtr\ a\ ->\ (Ptr\ a\ ->\ IO\ b)\ ->\ IO\ b
116 \end{tabular}]\haddockbegindoc
117 This is a way to look at the pointer living inside a
118 foreign object. This function takes a function which is
119 applied to that pointer. The resulting \haddockid{IO} action is then
120 executed. The foreign object is kept alive at least during
121 the whole action, even if it is not used directly
122 inside. Note that it is not safe to return the pointer from
123 the action and use it after the action completes. All uses
124 of the pointer should be inside the
125 \haddockid{withForeignPtr} bracket. The reason for
126 this unsafeness is the same as for
127 \haddockid{unsafeForeignPtrToPtr} below: the finalizer
128 may run earlier than expected, because the compiler can only
129 track usage of the \haddockid{ForeignPtr} object, not
130 a \haddockid{Ptr} object made from it.
131 \par
132 This function is normally used for marshalling data to
133 or from the object pointed to by the
134 \haddockid{ForeignPtr}, using the operations from the
135 \haddockid{Storable} class.
136 \par
137
138 \end{haddockdesc}
139 \subsection{Low-level operations
140 }
141 \begin{haddockdesc}
142 \item[\begin{tabular}{@{}l}
143 unsafeForeignPtrToPtr\ ::\ ForeignPtr\ a\ ->\ Ptr\ a
144 \end{tabular}]\haddockbegindoc
145 This function extracts the pointer component of a foreign
146 pointer. This is a potentially dangerous operations, as if the
147 argument to \haddockid{unsafeForeignPtrToPtr} is the last usage
148 occurrence of the given foreign pointer, then its finalizer(s) will
149 be run, which potentially invalidates the plain pointer just
150 obtained. Hence, \haddockid{touchForeignPtr} must be used
151 wherever it has to be guaranteed that the pointer lives on - i.e.,
152 has another usage occurrence.
153 \par
154 To avoid subtle coding errors, hand written marshalling code
155 should preferably use \haddocktt{Foreign.ForeignPtr.withForeignPtr} rather
156 than combinations of \haddockid{unsafeForeignPtrToPtr} and
157 \haddockid{touchForeignPtr}. However, the latter routines
158 are occasionally preferred in tool generated marshalling code.
159 \par
160
161 \end{haddockdesc}
162 \begin{haddockdesc}
163 \item[\begin{tabular}{@{}l}
164 touchForeignPtr\ ::\ ForeignPtr\ a\ ->\ IO\ ()
165 \end{tabular}]\haddockbegindoc
166 This function ensures that the foreign object in
167 question is alive at the given place in the sequence of IO
168 actions. In particular \haddocktt{Foreign.ForeignPtr.withForeignPtr}
169 does a \haddockid{touchForeignPtr} after it
170 executes the user action.
171 \par
172 Note that this function should not be used to express dependencies
173 between finalizers on \haddockid{ForeignPtr}s. For example, if the finalizer
174 for a \haddockid{ForeignPtr} \haddocktt{F1} calls \haddockid{touchForeignPtr} on a second
175 \haddockid{ForeignPtr} \haddocktt{F2}, then the only guarantee is that the finalizer
176 for \haddocktt{F2} is never started before the finalizer for \haddocktt{F1}. They
177 might be started together if for example both \haddocktt{F1} and \haddocktt{F2} are
178 otherwise unreachable, and in that case the scheduler might end up
179 running the finalizer for \haddocktt{F2} first.
180 \par
181 In general, it is not recommended to use finalizers on separate
182 objects with ordering constraints between them. To express the
183 ordering robustly requires explicit synchronisation using \haddocktt{MVar}s
184 between the finalizers, but even then the runtime sometimes runs
185 multiple finalizers sequentially in a single thread (for
186 performance reasons), so synchronisation between finalizers could
187 result in artificial deadlock. Another alternative is to use
188 explicit reference counting.
189 \par
190
191 \end{haddockdesc}
192 \begin{haddockdesc}
193 \item[\begin{tabular}{@{}l}
194 castForeignPtr\ ::\ ForeignPtr\ a\ ->\ ForeignPtr\ b
195 \end{tabular}]\haddockbegindoc
196 This function casts a \haddockid{ForeignPtr}
197 parameterised by one type into another type.
198 \par
199
200 \end{haddockdesc}
201 \subsection{Allocating managed memory
202 }
203 \begin{haddockdesc}
204 \item[\begin{tabular}{@{}l}
205 mallocForeignPtr\ ::\ Storable\ a\ =>\ IO\ (ForeignPtr\ a)
206 \end{tabular}]\haddockbegindoc
207 Allocate some memory and return a \haddockid{ForeignPtr} to it. The memory
208 will be released automatically when the \haddockid{ForeignPtr} is discarded.
209 \par
210 \haddockid{mallocForeignPtr} is equivalent to
211 \par
212 \begin{quote}
213 {\haddockverb\begin{verbatim}
214 do { p <- malloc; newForeignPtr finalizerFree p }
215 \end{verbatim}}
216 \end{quote}
217 although it may be implemented differently internally: you may not
218 assume that the memory returned by \haddockid{mallocForeignPtr} has been
219 allocated with \haddocktt{Foreign.Marshal.Alloc.malloc}.
220 \par
221 GHC notes: \haddockid{mallocForeignPtr} has a heavily optimised
222 implementation in GHC. It uses pinned memory in the garbage
223 collected heap, so the \haddockid{ForeignPtr} does not require a finalizer to
224 free the memory. Use of \haddockid{mallocForeignPtr} and associated
225 functions is strongly recommended in preference to \haddocktt{newForeignPtr}
226 with a finalizer.
227 \par
228
229 \end{haddockdesc}
230 \begin{haddockdesc}
231 \item[\begin{tabular}{@{}l}
232 mallocForeignPtrBytes\ ::\ Int\ ->\ IO\ (ForeignPtr\ a)
233 \end{tabular}]\haddockbegindoc
234 This function is similar to \haddockid{mallocForeignPtr}, except that the
235 size of the memory required is given explicitly as a number of bytes.
236 \par
237
238 \end{haddockdesc}
239 \begin{haddockdesc}
240 \item[\begin{tabular}{@{}l}
241 mallocForeignPtrArray\ ::\ Storable\ a\ =>\ Int\ ->\ IO\ (ForeignPtr\ a)
242 \end{tabular}]\haddockbegindoc
243 This function is similar to \haddocktt{Foreign.Marshal.Array.mallocArray},
244 but yields a memory area that has a finalizer attached that releases
245 the memory area. As with \haddockid{mallocForeignPtr}, it is not guaranteed that
246 the block of memory was allocated by \haddocktt{Foreign.Marshal.Alloc.malloc}.
247 \par
248
249 \end{haddockdesc}
250 \begin{haddockdesc}
251 \item[\begin{tabular}{@{}l}
252 mallocForeignPtrArray0\ ::\ Storable\ a\ =>\ Int\ ->\ IO\ (ForeignPtr\ a)
253 \end{tabular}]\haddockbegindoc
254 This function is similar to \haddocktt{Foreign.Marshal.Array.mallocArray0},
255 but yields a memory area that has a finalizer attached that releases
256 the memory area. As with \haddockid{mallocForeignPtr}, it is not guaranteed that
257 the block of memory was allocated by \haddocktt{Foreign.Marshal.Alloc.malloc}.
258 \par
259
260 \end{haddockdesc}