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.</para>
257 <para>NOTE: when linking the final program, it is normally
258 easiest to do the link using GHC, although this isn't
259 essential. If you do use GHC, then don't forget the flag
260 <option>-no-hs-main</option><indexterm><primary><option>-no-hs-main</option></primary>
261 </indexterm>, otherwise GHC will try to link
262 to the <literal>Main</literal> Haskell module.</para>
265 <sect3 id="ffi-library">
266 <title>Making a Haskell library that can be called from foreign
269 <para>The scenario here is much like in <xref linkend="using-own-main"
270 />, except that the aim is not to link a complete program, but to
271 make a library from Haskell code that can be deployed in the same
272 way that you would deploy a library of C code.</para>
274 <para>The main requirement here is that the runtime needs to be
275 initialized before any Haskell code can be called, so your library
276 should provide initialisation and deinitialisation entry points,
277 implemented in C or C++. For example:</para>
280 HsBool mylib_init(void){
284 // Initialize Haskell runtime
285 hs_init(&argc, &argv);
287 // Tell Haskell about all root modules
288 hs_add_root(__stginit_Foo);
290 // do any other initialization here and
291 // return false if there was a problem
295 void mylib_end(void){
300 <para>The initialisation routine, <literal>mylib_init</literal>, calls
301 <literal>hs_init()</literal> and <literal>hs_add_root()</literal> as
302 normal to initialise the Haskell runtime, and the corresponding
303 deinitialisation function <literal>mylib_end()</literal> calls
304 <literal>hs_exit()</literal> to shut down the runtime.</para>
308 <title>On the use of <literal>hs_exit()</literal></title>
310 <para><literal>hs_exit()</literal> normally causes the termination of
311 any running Haskell threads in the system, and when
312 <literal>hs_exit()</literal> returns, there will be no more Haskell
313 threads running. The runtime will then shut down the system in an
314 orderly way, generating profiling
315 output and statistics if necessary, and freeing all the memory it
318 <para>It isn't always possible to terminate a Haskell thread forcibly:
319 for example, the thread might be currently executing a foreign call,
320 and we have no way to force the foreign call to complete. What's
321 more, the runtime must
322 assume that in the worst case the Haskell code and runtime are about
323 to be removed from memory (e.g. if this is a <link linkend="win32-dlls">Windows DLL</link>,
324 <literal>hs_exit()</literal> is normally called before unloading the
325 DLL). So <literal>hs_exit()</literal> <emphasis>must</emphasis> wait
326 until all outstanding foreign calls return before it can return
329 <para>The upshot of this is that if you have Haskell threads that are
330 blocked in foreign calls, then <literal>hs_exit()</literal> may hang
331 (or possibly busy-wait) until the calls return. Therefore it's a
332 good idea to make sure you don't have any such threads in the system
333 when calling <literal>hs_exit()</literal>. This includes any threads
334 doing I/O, because I/O may (or may not, depending on the
335 type of I/O and the platform) be implemented using blocking foreign
338 <para>The GHC runtime treats program exit as a special case, to avoid
339 the need to wait for blocked threads when a standalone
340 executable exits. Since the program and all its threads are about to
341 terminate at the same time that the code is removed from memory, it
342 isn't necessary to ensure that the threads have exited first.
343 (Unofficially, if you want to use this fast and loose version of
344 <literal>hs_exit()</literal>, then call
345 <literal>shutdownHaskellAndExit()</literal> instead).</para>
349 <sect2 id="glasgow-foreign-headers">
350 <title>Using function headers</title>
352 <indexterm><primary>C calls, function headers</primary></indexterm>
354 <para>When generating C (using the <option>-fvia-C</option>
355 flag), one can assist the C compiler in detecting type
356 errors by using the <option>-#include</option> directive
357 (<xref linkend="options-C-compiler"/>) to provide
358 <filename>.h</filename> files containing function
361 <para>For example,</para>
366 void initialiseEFS (HsInt size);
367 HsInt terminateEFS (void);
368 HsForeignObj emptyEFS(void);
369 HsForeignObj updateEFS (HsForeignObj a, HsInt i, HsInt x);
370 HsInt lookupEFS (HsForeignObj a, HsInt i);
373 <para>The types <literal>HsInt</literal>,
374 <literal>HsForeignObj</literal> etc. are described in the H98 FFI
377 <para>Note that this approach is only
378 <emphasis>essential</emphasis> for returning
379 <literal>float</literal>s (or if <literal>sizeof(int) !=
380 sizeof(int *)</literal> on your architecture) but is a Good
381 Thing for anyone who cares about writing solid code. You're
382 crazy not to do it.</para>
385 What if you are importing a module from another package, and
386 a cross-module inlining exposes a foreign call that needs a supporting
387 <option>-#include</option>? If the imported module is from the same package as
388 the module being compiled, you should supply all the <option>-#include</option>
389 that you supplied when compiling the imported module. If the imported module comes
390 from another package, you won't necessarily know what the appropriate
391 <option>-#include</option> options are; but they should be in the package
392 configuration, which GHC knows about. So if you are building a package using
393 Cabal, remember to put all those include files in the package
394 description (see the <literal>includes</literal> field in the Cabal
395 documentation).</para>
398 It is also possible, according the FFI specification, to put the
399 <option>-#include</option> option in the foreign import
402 foreign import "foo.h f" f :: Int -> IO Int
404 When compiling this module, GHC will generate a C file that includes
405 the specified <option>-#include</option>. However, GHC
406 <emphasis>disables</emphasis> cross-module inlining for such foreign
407 calls, because it doesn't transport the <option>-#include</option>
408 information across module boundaries. (There is no fundamental reason for this;
409 it was just tiresome to implement. The wrapper, which unboxes the arguments
410 etc, is still inlined across modules.) So if you want the foreign call itself
411 to be inlined across modules, use the command-line and package-configuration
412 <option>-#include</option> mechanism.
415 <sect3 id="finding-header-files">
416 <title>Finding Header files</title>
418 <para>Header files named by the <option>-#include</option>
419 option or in a <literal>foreign import</literal> declaration
420 are searched for using the C compiler's usual search path.
421 You can add directories to this search path using the
422 <option>-I</option> option (see <xref
423 linkend="c-pre-processor"/>).</para>
425 <para>Note: header files are ignored unless compiling via C.
426 If you had been compiling your code using the native code
427 generator (the default) and suddenly switch to compiling via
428 C, then you can get unexpected errors about missing include
429 files. Compiling via C is enabled automatically when certain
430 options are given (eg. <option>-O</option> and
431 <option>-prof</option> both enable
432 <option>-fvia-C</option>).</para>
438 <title>Memory Allocation</title>
440 <para>The FFI libraries provide several ways to allocate memory
441 for use with the FFI, and it isn't always clear which way is the
442 best. This decision may be affected by how efficient a
443 particular kind of allocation is on a given compiler/platform,
444 so this section aims to shed some light on how the different
445 kinds of allocation perform with GHC.</para>
449 <term><literal>alloca</literal> and friends</term>
451 <para>Useful for short-term allocation when the allocation
452 is intended to scope over a given <literal>IO</literal>
453 computation. This kind of allocation is commonly used
454 when marshalling data to and from FFI functions.</para>
456 <para>In GHC, <literal>alloca</literal> is implemented
457 using <literal>MutableByteArray#</literal>, so allocation
458 and deallocation are fast: much faster than C's
459 <literal>malloc/free</literal>, but not quite as fast as
460 stack allocation in C. Use <literal>alloca</literal>
461 whenever you can.</para>
466 <term><literal>mallocForeignPtr</literal></term>
468 <para>Useful for longer-term allocation which requires
469 garbage collection. If you intend to store the pointer to
470 the memory in a foreign data structure, then
471 <literal>mallocForeignPtr</literal> is
472 <emphasis>not</emphasis> a good choice, however.</para>
474 <para>In GHC, <literal>mallocForeignPtr</literal> is also
475 implemented using <literal>MutableByteArray#</literal>.
476 Although the memory is pointed to by a
477 <literal>ForeignPtr</literal>, there are no actual
478 finalizers involved (unless you add one with
479 <literal>addForeignPtrFinalizer</literal>), and the
480 deallocation is done using GC, so
481 <literal>mallocForeignPtr</literal> is normally very
487 <term><literal>malloc/free</literal></term>
489 <para>If all else fails, then you need to resort to
490 <literal>Foreign.malloc</literal> and
491 <literal>Foreign.free</literal>. These are just wrappers
492 around the C functions of the same name, and their
493 efficiency will depend ultimately on the implementations
494 of these functions in your platform's C library. We
495 usually find <literal>malloc</literal> and
496 <literal>free</literal> to be significantly slower than
497 the other forms of allocation above.</para>
502 <term><literal>Foreign.Marshal.Pool</literal></term>
504 <para>Pools are currently implemented using
505 <literal>malloc/free</literal>, so while they might be a
506 more convenient way to structure your memory allocation
507 than using one of the other forms of allocation, they
508 won't be any more efficient. We do plan to provide an
509 improved-performance implementation of Pools in the
510 future, however.</para>
519 ;;; Local Variables: ***
521 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***