1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!-- FFI docs as a chapter -->
6 Foreign function interface (FFI)
9 <para>GHC (mostly) conforms to the Haskell 98 Foreign Function Interface
10 Addendum 1.0, whose definition is available from <ulink url="http://www.haskell.org/"><literal>http://www.haskell.org/</literal></ulink>.</para>
12 <para>To enable FFI support in GHC, give the <option>-XForeignFunctionInterface</option><indexterm><primary><option>-XForeignFunctionInterface</option></primary>
13 </indexterm> flag.</para>
15 <para>GHC implements a number of GHC-specific extensions to the FFI
16 Addendum. These extensions are described in <xref linkend="ffi-ghcexts" />, but please note that programs using
17 these features are not portable. Hence, these features should be
18 avoided where possible.</para>
20 <para>The FFI libraries are documented in the accompanying library
21 documentation; see for example the
22 <ulink url="../libraries/base/Control-Concurrent.html"><literal>Foreign</literal></ulink> module.</para>
24 <sect1 id="ffi-ghcexts">
25 <title>GHC extensions to the FFI Addendum</title>
27 <para>The FFI features that are described in this section are specific to
28 GHC. Your code will not be portable to other compilers if you use them.</para>
31 <title>Unboxed types</title>
33 <para>The following unboxed types may be used as basic foreign types
34 (see FFI Addendum, Section 3.2): <literal>Int#</literal>,
35 <literal>Word#</literal>, <literal>Char#</literal>,
36 <literal>Float#</literal>, <literal>Double#</literal>,
37 <literal>Addr#</literal>, <literal>StablePtr# a</literal>,
38 <literal>MutableByteArray#</literal>, <literal>ForeignObj#</literal>,
39 and <literal>ByteArray#</literal>.</para>
42 <sect2 id="ffi-newtype-io">
43 <title>Newtype wrapping of the IO monad</title>
44 <para>The FFI spec requires the IO monad to appear in various places,
45 but it can sometimes be convenient to wrap the IO monad in a
46 <literal>newtype</literal>, thus:
48 newtype MyIO a = MIO (IO a)
50 (A reason for doing so might be to prevent the programmer from
51 calling arbitrary IO procedures in some part of the program.)
53 <para>The Haskell FFI already specifies that arguments and results of
54 foreign imports and exports will be automatically unwrapped if they are
55 newtypes (Section 3.2 of the FFI addendum). GHC extends the FFI by automatically unwrapping any newtypes that
56 wrap the IO monad itself.
57 More precisely, wherever the FFI specification requires an IO type, GHC will
58 accept any newtype-wrapping of an IO type. For example, these declarations are
61 foreign import foo :: Int -> MyIO Int
62 foreign import "dynamic" baz :: (Int -> MyIO Int) -> CInt -> MyIO Int
69 <title>Using the FFI with GHC</title>
71 <para>The following sections also give some hints and tips on the
72 use of the foreign function interface in GHC.</para>
74 <sect2 id="foreign-export-ghc">
75 <title>Using <literal>foreign export</literal> and <literal>foreign import ccall "wrapper"</literal> with GHC</title>
77 <indexterm><primary><literal>foreign export
78 </literal></primary><secondary>with GHC</secondary>
81 <para>When GHC compiles a module (say <filename>M.hs</filename>)
82 which uses <literal>foreign export</literal> or
83 <literal>foreign import "wrapper"</literal>, it generates two
84 additional files, <filename>M_stub.c</filename> and
85 <filename>M_stub.h</filename>. GHC will automatically compile
86 <filename>M_stub.c</filename> to generate
87 <filename>M_stub.o</filename> at the same time.</para>
89 <para>For a plain <literal>foreign export</literal>, the file
90 <filename>M_stub.h</filename> contains a C prototype for the
91 foreign exported function, and <filename>M_stub.c</filename>
92 contains its definition. For example, if we compile the
93 following module:</para>
98 foreign export ccall foo :: Int -> IO Int
101 foo n = return (length (f n))
105 f n = n:(f (n-1))</programlisting>
107 <para>Then <filename>Foo_stub.h</filename> will contain
108 something like this:</para>
112 extern HsInt foo(HsInt a0);</programlisting>
114 <para>and <filename>Foo_stub.c</filename> contains the
115 compiler-generated definition of <literal>foo()</literal>. To
116 invoke <literal>foo()</literal> from C, just <literal>#include
117 "Foo_stub.h"</literal> and call <literal>foo()</literal>.</para>
119 <para>The <filename>foo_stub.c</filename> and
120 <filename>foo_stub.h</filename> files can be redirected using the
121 <option>-stubdir</option> option; see <xref linkend="options-output"
124 <para>When linking the program, remember to include
125 <filename>M_stub.o</filename> in the final link command line, or
126 you'll get link errors for the missing function(s) (this isn't
127 necessary when building your program with <literal>ghc
128 ––make</literal>, as GHC will automatically link in the
129 correct bits).</para>
131 <sect3 id="using-own-main">
132 <title>Using your own <literal>main()</literal></title>
134 <para>Normally, GHC's runtime system provides a
135 <literal>main()</literal>, which arranges to invoke
136 <literal>Main.main</literal> in the Haskell program. However,
137 you might want to link some Haskell code into a program which
138 has a main function written in another language, say C. In
139 order to do this, you have to initialize the Haskell runtime
140 system explicitly.</para>
142 <para>Let's take the example from above, and invoke it from a
143 standalone C program. Here's the C code:</para>
146 #include <stdio.h>
149 #ifdef __GLASGOW_HASKELL__
150 #include "foo_stub.h"
153 #ifdef __GLASGOW_HASKELL__
154 extern void __stginit_Foo ( void );
157 int main(int argc, char *argv[])
161 hs_init(&argc, &argv);
162 #ifdef __GLASGOW_HASKELL__
163 hs_add_root(__stginit_Foo);
166 for (i = 0; i < 5; i++) {
167 printf("%d\n", foo(2500));
174 <para>We've surrounded the GHC-specific bits with
175 <literal>#ifdef __GLASGOW_HASKELL__</literal>; the rest of the
176 code should be portable across Haskell implementations that
177 support the FFI standard.</para>
179 <para>The call to <literal>hs_init()</literal>
180 initializes GHC's runtime system. Do NOT try to invoke any
181 Haskell functions before calling
182 <literal>hs_init()</literal>: bad things will
183 undoubtedly happen.</para>
185 <para>We pass references to <literal>argc</literal> and
186 <literal>argv</literal> to <literal>hs_init()</literal>
187 so that it can separate out any arguments for the RTS
188 (i.e. those arguments between
189 <literal>+RTS...-RTS</literal>).</para>
192 <function>hs_add_root</function><indexterm><primary><function>hs_add_root</function></primary>
193 </indexterm>, a GHC-specific interface which is required to
194 initialise the Haskell modules in the program. The argument
195 to <function>hs_add_root</function> should be the name of the
196 initialization function for the "root" module in your program
197 - in other words, the module which directly or indirectly
198 imports all the other Haskell modules in the program. In a
199 standalone Haskell program the root module is normally
200 <literal>Main</literal>, but when you are using Haskell code
201 from a library it may not be. If your program has multiple
202 root modules, then you can call
203 <function>hs_add_root</function> multiple times, one for each
204 root. The name of the initialization function for module
205 <replaceable>M</replaceable> is
206 <literal>__stginit_<replaceable>M</replaceable></literal>, and
207 it may be declared as an external function symbol as in the
208 code above. Note that the symbol name should be transformed
209 according to the Z-encoding:</para>
212 <tgroup cols="2" align="left" colsep="1" rowsep="1">
215 <entry>Character</entry>
216 <entry>Replacement</entry>
221 <entry><literal>.</literal></entry>
222 <entry><literal>zd</literal></entry>
225 <entry><literal>_</literal></entry>
226 <entry><literal>zu</literal></entry>
229 <entry><literal>`</literal></entry>
230 <entry><literal>zq</literal></entry>
233 <entry><literal>Z</literal></entry>
234 <entry><literal>ZZ</literal></entry>
237 <entry><literal>z</literal></entry>
238 <entry><literal>zz</literal></entry>
244 <para>After we've finished invoking our Haskell functions, we
245 can call <literal>hs_exit()</literal>, which terminates the
248 <para>There can be multiple calls to
249 <literal>hs_init()</literal>, but each one should be matched
250 by one (and only one) call to
251 <literal>hs_exit()</literal><footnote><para>The outermost
252 <literal>hs_exit()</literal> will actually de-initialise the
253 system. NOTE that currently GHC's runtime cannot reliably
254 re-initialise after this has happened,
255 see <xref linkend="ffi-divergence" />.</para>
258 <para>NOTE: when linking the final program, it is normally
259 easiest to do the link using GHC, although this isn't
260 essential. If you do use GHC, then don't forget the flag
261 <option>-no-hs-main</option><indexterm><primary><option>-no-hs-main</option></primary>
262 </indexterm>, otherwise GHC will try to link
263 to the <literal>Main</literal> Haskell module.</para>
266 <sect3 id="ffi-library">
267 <title>Making a Haskell library that can be called from foreign
270 <para>The scenario here is much like in <xref linkend="using-own-main"
271 />, except that the aim is not to link a complete program, but to
272 make a library from Haskell code that can be deployed in the same
273 way that you would deploy a library of C code.</para>
275 <para>The main requirement here is that the runtime needs to be
276 initialized before any Haskell code can be called, so your library
277 should provide initialisation and deinitialisation entry points,
278 implemented in C or C++. For example:</para>
281 HsBool mylib_init(void){
285 // Initialize Haskell runtime
286 hs_init(&argc, &argv);
288 // Tell Haskell about all root modules
289 hs_add_root(__stginit_Foo);
291 // do any other initialization here and
292 // return false if there was a problem
296 void mylib_end(void){
301 <para>The initialisation routine, <literal>mylib_init</literal>, calls
302 <literal>hs_init()</literal> and <literal>hs_add_root()</literal> as
303 normal to initialise the Haskell runtime, and the corresponding
304 deinitialisation function <literal>mylib_end()</literal> calls
305 <literal>hs_exit()</literal> to shut down the runtime.</para>
310 <sect2 id="glasgow-foreign-headers">
311 <title>Using header files</title>
313 <indexterm><primary>C calls, function headers</primary></indexterm>
315 <para>C functions are normally declared using prototypes in a C
316 header file. Earlier versions of GHC (6.8.3 and
317 earlier) <literal>#include</literal>d the header file in
318 the C source file generated from the Haskell code, and the C
319 compiler could therefore check that the C function being
320 called via the FFI was being called at the right type.</para>
322 <para>GHC no longer includes external header files when
323 compiling via C, so this checking is not performed. The
324 change was made for compatibility with the native code backend
325 (<literal>-fasm</literal>) and to comply strictly with the FFI
326 specification, which requires that FFI calls are not subject
327 to macro expansion and other CPP conversions that may be
328 applied when using C header files. This approach also
329 simplifies the inlining of foreign calls across module and
330 package boundaries: there's no need for the header file to be
331 available when compiling an inlined version of a foreign call,
332 so the compiler is free to inline foreign calls in any
335 <para>The <literal>-#include</literal> option is now
336 deprecated, and the <literal>include-files</literal> field
337 in a Cabal package specification is ignored.</para>
342 <title>Memory Allocation</title>
344 <para>The FFI libraries provide several ways to allocate memory
345 for use with the FFI, and it isn't always clear which way is the
346 best. This decision may be affected by how efficient a
347 particular kind of allocation is on a given compiler/platform,
348 so this section aims to shed some light on how the different
349 kinds of allocation perform with GHC.</para>
353 <term><literal>alloca</literal> and friends</term>
355 <para>Useful for short-term allocation when the allocation
356 is intended to scope over a given <literal>IO</literal>
357 computation. This kind of allocation is commonly used
358 when marshalling data to and from FFI functions.</para>
360 <para>In GHC, <literal>alloca</literal> is implemented
361 using <literal>MutableByteArray#</literal>, so allocation
362 and deallocation are fast: much faster than C's
363 <literal>malloc/free</literal>, but not quite as fast as
364 stack allocation in C. Use <literal>alloca</literal>
365 whenever you can.</para>
370 <term><literal>mallocForeignPtr</literal></term>
372 <para>Useful for longer-term allocation which requires
373 garbage collection. If you intend to store the pointer to
374 the memory in a foreign data structure, then
375 <literal>mallocForeignPtr</literal> is
376 <emphasis>not</emphasis> a good choice, however.</para>
378 <para>In GHC, <literal>mallocForeignPtr</literal> is also
379 implemented using <literal>MutableByteArray#</literal>.
380 Although the memory is pointed to by a
381 <literal>ForeignPtr</literal>, there are no actual
382 finalizers involved (unless you add one with
383 <literal>addForeignPtrFinalizer</literal>), and the
384 deallocation is done using GC, so
385 <literal>mallocForeignPtr</literal> is normally very
391 <term><literal>malloc/free</literal></term>
393 <para>If all else fails, then you need to resort to
394 <literal>Foreign.malloc</literal> and
395 <literal>Foreign.free</literal>. These are just wrappers
396 around the C functions of the same name, and their
397 efficiency will depend ultimately on the implementations
398 of these functions in your platform's C library. We
399 usually find <literal>malloc</literal> and
400 <literal>free</literal> to be significantly slower than
401 the other forms of allocation above.</para>
406 <term><literal>Foreign.Marshal.Pool</literal></term>
408 <para>Pools are currently implemented using
409 <literal>malloc/free</literal>, so while they might be a
410 more convenient way to structure your memory allocation
411 than using one of the other forms of allocation, they
412 won't be any more efficient. We do plan to provide an
413 improved-performance implementation of Pools in the
414 future, however.</para>
420 <sect2 id="ffi-threads">
421 <title>Multi-threading and the FFI</title>
423 <para>In order to use the FFI in a multi-threaded setting, you must
424 use the <option>-threaded</option> option
425 (see <xref linkend="options-linker" />).</para>
428 <title>Foreign imports and multi-threading</title>
430 <para>When you call a <literal>foreign import</literal>ed
431 function that is annotated as <literal>safe</literal> (the
432 default), and the program was linked
433 using <option>-threaded</option>, then the call will run
434 concurrently with other running Haskell threads. If the
435 program was linked without <option>-threaded</option>,
436 then the other Haskell threads will be blocked until the
439 <para>This means that if you need to make a foreign call to
440 a function that takes a long time or blocks indefinitely,
441 then you should mark it <literal>safe</literal> and
442 use <option>-threaded</option>. Some library functions
443 make such calls internally; their documentation should
444 indicate when this is the case.</para>
446 <para>If you are making foreign calls from multiple Haskell
447 threads and using <option>-threaded</option>, make sure that
448 the foreign code you are calling is thread-safe. In
449 particularly, some GUI libraries are not thread-safe and
450 require that the caller only invokes GUI methods from a
451 single thread. If this is the case, you may need to
452 restrict your GUI operations to a single Haskell thread,
453 and possibly also use a bound thread (see
454 <xref linkend="haskell-threads-and-os-threads" />).</para>
456 <para>Note that foreign calls made by different Haskell
457 threads may execute in <emphasis>parallel</emphasis>, even
458 when the <literal>+RTS -N</literal> flag is not being used
459 (<xref linkend="parallel-options" />). The <literal>+RTS
460 -N</literal> flag controls parallel execution of Haskell
461 threads, but there may be an arbitrary number of foreign
462 calls in progress at any one time, regardless of
463 the <literal>+RTS -N</literal> value.</para>
466 <sect3 id="haskell-threads-and-os-threads">
467 <title>The relationship between Haskell threads and OS
470 <para>Normally there is no fixed relationship between Haskell
471 threads and OS threads. This means that when you make a
472 foreign call, that call may take place in an unspecified OS
473 thread. Furthermore, there is no guarantee that multiple
474 calls made by one Haskell thread will be made by the same OS
477 <para>This usually isn't a problem, and it allows the GHC
478 runtime system to make efficient use of OS thread resources.
479 However, there are cases where it is useful to have more
480 control over which OS thread is used, for example when
481 calling foreign code that makes use of thread-local state.
482 For cases like this, we provide <emphasis>bound
483 threads</emphasis>, which are Haskell threads tied to a
484 particular OS thread. For information on bound threads, see
486 for the <ulink url="../libraries/base/Control-Concurrent.html"><literal>Control.Concurrent</literal></ulink>
491 <title>Foreign exports and multi-threading</title>
493 <para>When the program is linked
494 with <option>-threaded</option>, then you may
495 invoke <literal>foreign export</literal>ed functions from
496 multiple OS threads concurrently. The runtime system must
497 be initialised as usual by
498 calling <literal>hs_init()</literal>
499 and <literal>hs_add_root</literal>, and these calls must
500 complete before invoking any <literal>foreign
501 export</literal>ed functions.</para>
505 <title>On the use of <literal>hs_exit()</literal></title>
507 <para><literal>hs_exit()</literal> normally causes the termination of
508 any running Haskell threads in the system, and when
509 <literal>hs_exit()</literal> returns, there will be no more Haskell
510 threads running. The runtime will then shut down the system in an
511 orderly way, generating profiling
512 output and statistics if necessary, and freeing all the memory it
515 <para>It isn't always possible to terminate a Haskell thread forcibly:
516 for example, the thread might be currently executing a foreign call,
517 and we have no way to force the foreign call to complete. What's
518 more, the runtime must
519 assume that in the worst case the Haskell code and runtime are about
520 to be removed from memory (e.g. if this is a <link linkend="win32-dlls">Windows DLL</link>,
521 <literal>hs_exit()</literal> is normally called before unloading the
522 DLL). So <literal>hs_exit()</literal> <emphasis>must</emphasis> wait
523 until all outstanding foreign calls return before it can return
526 <para>The upshot of this is that if you have Haskell threads that are
527 blocked in foreign calls, then <literal>hs_exit()</literal> may hang
528 (or possibly busy-wait) until the calls return. Therefore it's a
529 good idea to make sure you don't have any such threads in the system
530 when calling <literal>hs_exit()</literal>. This includes any threads
531 doing I/O, because I/O may (or may not, depending on the
532 type of I/O and the platform) be implemented using blocking foreign
535 <para>The GHC runtime treats program exit as a special case, to avoid
536 the need to wait for blocked threads when a standalone
537 executable exits. Since the program and all its threads are about to
538 terminate at the same time that the code is removed from memory, it
539 isn't necessary to ensure that the threads have exited first.
540 (Unofficially, if you want to use this fast and loose version of
541 <literal>hs_exit()</literal>, then call
542 <literal>shutdownHaskellAndExit()</literal> instead).</para>
550 ;;; Local Variables: ***
552 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***