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://haskell.org/"><literal>http://haskell.org/</literal></ulink>.</para>
12 <para>To enable FFI support in GHC, give the <option>-fffi</option><indexterm><primary><option>-fffi</option></primary>
14 the <option>-fglasgow-exts</option><indexterm><primary><option>-fglasgow-exts</option></primary>
15 </indexterm> flag which implies <option>-fffi</option>
18 <para>GHC implements a number of GHC-specific extensions to the FFI
19 Addendum. These extensions are described in <xref linkend="ffi-ghcexts" />, but please note that programs using
20 these features are not portable. Hence, these features should be
21 avoided where possible.</para>
23 <para>The FFI libraries are documented in the accompanying library
24 documentation; see for example the
25 <ulink url="../libraries/base/Control-Concurrent.html"><literal>Foreign</literal></ulink> module.</para>
27 <sect1 id="ffi-ghcexts">
28 <title>GHC extensions to the FFI Addendum</title>
30 <para>The FFI features that are described in this section are specific to
31 GHC. Your code will not be portable to other compilers if you use them.</para>
34 <title>Unboxed types</title>
36 <para>The following unboxed types may be used as basic foreign types
37 (see FFI Addendum, Section 3.2): <literal>Int#</literal>,
38 <literal>Word#</literal>, <literal>Char#</literal>,
39 <literal>Float#</literal>, <literal>Double#</literal>,
40 <literal>Addr#</literal>, <literal>StablePtr# a</literal>,
41 <literal>MutableByteArray#</literal>, <literal>ForeignObj#</literal>,
42 and <literal>ByteArray#</literal>.</para>
45 <sect2 id="ffi-newtype-io">
46 <title>Newtype wrapping of the IO monad</title>
47 <para>The FFI spec requires the IO monad to appear in various places,
48 but it can sometimes be convenient to wrap the IO monad in a
49 <literal>newtype</literal>, thus:
51 newtype MyIO a = MIO (IO a)
53 (A reason for doing so might be to prevent the programmer from
54 calling arbitrary IO procedures in some part of the program.)
56 <para>The Haskell FFI already specifies that arguments and results of
57 foreign imports and exports will be automatically unwrapped if they are
58 newtypes (Section 3.2 of the FFI addendum). GHC extends the FFI by automatically unnwrapping any newtypes that
59 wrap the IO monad itself.
60 More precisely, wherever the FFI specification requires an IO type, GHC will
61 accept any newtype-wrapping of an IO type. For example, these declarations are
64 foreign import foo :: Int -> MyIO Int
65 foreign import "dynamic" baz :: (Int -> MyIO Int) -> CInt -> MyIO Int
72 <title>Using the FFI with GHC</title>
74 <para>The following sections also give some hints and tips on the
75 use of the foreign function interface in GHC.</para>
77 <sect2 id="foreign-export-ghc">
78 <title>Using <literal>foreign export</literal> and <literal>foreign import ccall "wrapper"</literal> with GHC</title>
80 <indexterm><primary><literal>foreign export
81 </literal></primary><secondary>with GHC</secondary>
84 <para>When GHC compiles a module (say <filename>M.hs</filename>)
85 which uses <literal>foreign export</literal> or
86 <literal>foreign import "wrapper"</literal>, it generates two
87 additional files, <filename>M_stub.c</filename> and
88 <filename>M_stub.h</filename>. GHC will automatically compile
89 <filename>M_stub.c</filename> to generate
90 <filename>M_stub.o</filename> at the same time.</para>
92 <para>For a plain <literal>foreign export</literal>, the file
93 <filename>M_stub.h</filename> contains a C prototype for the
94 foreign exported function, and <filename>M_stub.c</filename>
95 contains its definition. For example, if we compile the
96 following module:</para>
101 foreign export ccall foo :: Int -> IO Int
104 foo n = return (length (f n))
108 f n = n:(f (n-1))</programlisting>
110 <para>Then <filename>Foo_stub.h</filename> will contain
111 something like this:</para>
115 extern HsInt foo(HsInt a0);</programlisting>
117 <para>and <filename>Foo_stub.c</filename> contains the
118 compiler-generated definition of <literal>foo()</literal>. To
119 invoke <literal>foo()</literal> from C, just <literal>#include
120 "Foo_stub.h"</literal> and call <literal>foo()</literal>.</para>
122 <para>The <filename>foo_stub.c</filename> and
123 <filename>foo_stub.h</filename> files can be redirected using the
124 <option>-stubdir</option> option; see <xref linkend="options-output"
127 <para>When linking the program, remember to include
128 <filename>M_stub.o</filename> in the final link command line, or
129 you'll get link errors for the missing function(s) (this isn't
130 necessary when building your program with <literal>ghc
131 ––make</literal>, as GHC will automatically link in the
132 correct bits).</para>
134 <sect3 id="using-own-main">
135 <title>Using your own <literal>main()</literal></title>
137 <para>Normally, GHC's runtime system provides a
138 <literal>main()</literal>, which arranges to invoke
139 <literal>Main.main</literal> in the Haskell program. However,
140 you might want to link some Haskell code into a program which
141 has a main function written in another language, say C. In
142 order to do this, you have to initialize the Haskell runtime
143 system explicitly.</para>
145 <para>Let's take the example from above, and invoke it from a
146 standalone C program. Here's the C code:</para>
149 #include <stdio.h>
152 #ifdef __GLASGOW_HASKELL__
153 #include "foo_stub.h"
156 #ifdef __GLASGOW_HASKELL__
157 extern void __stginit_Foo ( void );
160 int main(int argc, char *argv[])
164 hs_init(&argc, &argv);
165 #ifdef __GLASGOW_HASKELL__
166 hs_add_root(__stginit_Foo);
169 for (i = 0; i < 5; i++) {
170 printf("%d\n", foo(2500));
177 <para>We've surrounded the GHC-specific bits with
178 <literal>#ifdef __GLASGOW_HASKELL__</literal>; the rest of the
179 code should be portable across Haskell implementations that
180 support the FFI standard.</para>
182 <para>The call to <literal>hs_init()</literal>
183 initializes GHC's runtime system. Do NOT try to invoke any
184 Haskell functions before calling
185 <literal>hs_init()</literal>: bad things will
186 undoubtedly happen.</para>
188 <para>We pass references to <literal>argc</literal> and
189 <literal>argv</literal> to <literal>hs_init()</literal>
190 so that it can separate out any arguments for the RTS
191 (i.e. those arguments between
192 <literal>+RTS...-RTS</literal>).</para>
195 <function>hs_add_root</function><indexterm><primary><function>hs_add_root</function></primary>
196 </indexterm>, a GHC-specific interface which is required to
197 initialise the Haskell modules in the program. The argument
198 to <function>hs_add_root</function> should be the name of the
199 initialization function for the "root" module in your program
200 - in other words, the module which directly or indirectly
201 imports all the other Haskell modules in the program. In a
202 standalone Haskell program the root module is normally
203 <literal>Main</literal>, but when you are using Haskell code
204 from a library it may not be. If your program has multiple
205 root modules, then you can call
206 <function>hs_add_root</function> multiple times, one for each
207 root. The name of the initialization function for module
208 <replaceable>M</replaceable> is
209 <literal>__stginit_<replaceable>M</replaceable></literal>, and
210 it may be declared as an external function symbol as in the
211 code above. Note that the symbol name should be transformed
212 according to the Z-encoding:</para>
215 <tgroup cols="2" align="left" colsep="1" rowsep="1">
218 <entry>Character</entry>
219 <entry>Replacement</entry>
224 <entry><literal>.</literal></entry>
225 <entry><literal>zd</literal></entry>
228 <entry><literal>_</literal></entry>
229 <entry><literal>zu</literal></entry>
232 <entry><literal>`</literal></entry>
233 <entry><literal>zq</literal></entry>
236 <entry><literal>Z</literal></entry>
237 <entry><literal>ZZ</literal></entry>
240 <entry><literal>z</literal></entry>
241 <entry><literal>zz</literal></entry>
247 <para>After we've finished invoking our Haskell functions, we
248 can call <literal>hs_exit()</literal>, which terminates the
251 <para>There can be multiple calls to
252 <literal>hs_init()</literal>, but each one should be matched
253 by one (and only one) call to
254 <literal>hs_exit()</literal><footnote><para>The outermost
255 <literal>hs_exit()</literal> will actually de-initialise the
256 system. NOTE that currently GHC's runtime cannot reliably
257 re-initialise after this has happened.</para>
260 <para>NOTE: when linking the final program, it is normally
261 easiest to do the link using GHC, although this isn't
262 essential. If you do use GHC, then don't forget the flag
263 <option>-no-hs-main</option><indexterm><primary><option>-no-hs-main</option></primary>
264 </indexterm>, otherwise GHC will try to link
265 to the <literal>Main</literal> Haskell module.</para>
268 <sect3 id="ffi-library">
269 <title>Making a Haskell library that can be called from foreign
272 <para>The scenario here is much like in <xref linkend="using-own-main"
273 />, except that the aim is not to link a complete program, but to
274 make a library from Haskell code that can be deployed in the same
275 way that you would deploy a library of C code.</para>
277 <para>The main requirement here is that the runtime needs to be
278 initialized before any Haskell code can be called, so your library
279 should provide initialisation and deinitialisation entry points,
280 implemented in C or C++. For example:</para>
283 HsBool mylib_init(void){
287 // Initialize Haskell runtime
288 hs_init(&argc, &argv);
290 // Tell Haskell about all root modules
291 hs_add_root(__stginit_Foo);
293 // do any other initialization here and
294 // return false if there was a problem
298 void mylib_end(void){
303 <para>The intialisation routine, <literal>mylib_init</literal>, calls
304 <literal>hs_init()</literal> and <literal>hs_add_root()</literal> as
305 normal to initialise the Haskell runtime, and the corresponding
306 deinitialisation funtion <literal>mylib_end()</literal> calls
307 <literal>hs_exit()</literal> to shut down the runtime.</para>
311 <title>On the use of <literal>hs_exit()</literal></title>
313 <para><literal>hs_exit()</literal> normally causes the termination of
314 any running Haskell threads in the system, and when
315 <literal>hs_exit()</literal> returns, there will be no more Haskell
316 threads running. The runtime will then shut down the system in an
317 orderly way, generating profiling
318 output and statistics if necessary, and freeing all the memory it
321 <para>It isn't always possible to terminate a Haskell thread forcibly:
322 for example, the thread might be currently executing a foreign call,
323 and we have no way to force the foreign call to complete. What's
324 more, the runtime must
325 assume that in the worst case the Haskell code and runtime are about
326 to be removed from memory (e.g. if this is a <link linkend="win32-dlls">Windows DLL</link>,
327 <literal>hs_exit()</literal> is normally called before unloading the
328 DLL). So <literal>hs_exit()</literal> <emphasis>must</emphasis> wait
329 until all outstanding foreign calls return before it can return
332 <para>The upshot of this is that if you have Haskell threads that are
333 blocked in foreign calls, then <literal>hs_exit()</literal> may hang
334 (or possibly busy-wait) until the calls return. Therefore it's a
335 good idea to make sure you don't have any such threads in the system
336 when calling <literal>hs_exit()</literal>. This includes any threads
337 doing I/O, because I/O may (or may not, depending on the
338 type of I/O and the platform) be implemented using blocking foreign
341 <para>The GHC runtime treats program exit as a special case, to avoid
342 the need to wait for blocked threads when a standalone
343 executable exits. Since the program and all its threads are about to
344 terminate at the same time that the code is removed from memory, it
345 isn't necessary to ensure that the threads have exited first.
346 (Unofficially, if you want to use this fast and loose version of
347 <literal>hs_exit()</literal>, then call
348 <literal>shutdownHaskellAndExit()</literal> instead).</para>
352 <sect2 id="glasgow-foreign-headers">
353 <title>Using function headers</title>
355 <indexterm><primary>C calls, function headers</primary></indexterm>
357 <para>When generating C (using the <option>-fvia-C</option>
358 flag), one can assist the C compiler in detecting type
359 errors by using the <option>-#include</option> directive
360 (<xref linkend="options-C-compiler"/>) to provide
361 <filename>.h</filename> files containing function
364 <para>For example,</para>
369 void initialiseEFS (HsInt size);
370 HsInt terminateEFS (void);
371 HsForeignObj emptyEFS(void);
372 HsForeignObj updateEFS (HsForeignObj a, HsInt i, HsInt x);
373 HsInt lookupEFS (HsForeignObj a, HsInt i);
376 <para>The types <literal>HsInt</literal>,
377 <literal>HsForeignObj</literal> etc. are described in the H98 FFI
380 <para>Note that this approach is only
381 <emphasis>essential</emphasis> for returning
382 <literal>float</literal>s (or if <literal>sizeof(int) !=
383 sizeof(int *)</literal> on your architecture) but is a Good
384 Thing for anyone who cares about writing solid code. You're
385 crazy not to do it.</para>
388 What if you are importing a module from another package, and
389 a cross-module inlining exposes a foreign call that needs a supporting
390 <option>-#include</option>? If the imported module is from the same package as
391 the module being compiled, you should supply all the <option>-#include</option>
392 that you supplied when compiling the imported module. If the imported module comes
393 from another package, you won't necessarily know what the appropriate
394 <option>-#include</option> options are; but they should be in the package
395 configuration, which GHC knows about. So if you are building a package using
396 Cabal, remember to put all those include files in the package
397 description (see the <literal>includes</literal> field in the Cabal
398 documentation).</para>
401 It is also possible, according the FFI specification, to put the
402 <option>-#include</option> option in the foreign import
405 foreign import "foo.h f" f :: Int -> IO Int
407 When compiling this module, GHC will generate a C file that includes
408 the specified <option>-#include</option>. However, GHC
409 <emphasis>disables</emphasis> cross-module inlining for such foreign
410 calls, because it doesn't transport the <option>-#include</option>
411 information across module boundaries. (There is no fundamental reason for this;
412 it was just tiresome to implement. The wrapper, which unboxes the arguments
413 etc, is still inlined across modules.) So if you want the foreign call itself
414 to be inlined across modules, use the command-line and package-configuration
415 <option>-#include</option> mechanism.
418 <sect3 id="finding-header-files">
419 <title>Finding Header files</title>
421 <para>Header files named by the <option>-#include</option>
422 option or in a <literal>foreign import</literal> declaration
423 are searched for using the C compiler's usual search path.
424 You can add directories to this search path using the
425 <option>-I</option> option (see <xref
426 linkend="c-pre-processor"/>).</para>
428 <para>Note: header files are ignored unless compiling via C.
429 If you had been compiling your code using the native code
430 generator (the default) and suddenly switch to compiling via
431 C, then you can get unexpected errors about missing include
432 files. Compiling via C is enabled automatically when certain
433 options are given (eg. <option>-O</option> and
434 <option>-prof</option> both enable
435 <option>-fvia-C</option>).</para>
441 <title>Memory Allocation</title>
443 <para>The FFI libraries provide several ways to allocate memory
444 for use with the FFI, and it isn't always clear which way is the
445 best. This decision may be affected by how efficient a
446 particular kind of allocation is on a given compiler/platform,
447 so this section aims to shed some light on how the different
448 kinds of allocation perform with GHC.</para>
452 <term><literal>alloca</literal> and friends</term>
454 <para>Useful for short-term allocation when the allocation
455 is intended to scope over a given <literal>IO</literal>
456 computation. This kind of allocation is commonly used
457 when marshalling data to and from FFI functions.</para>
459 <para>In GHC, <literal>alloca</literal> is implemented
460 using <literal>MutableByteArray#</literal>, so allocation
461 and deallocation are fast: much faster than C's
462 <literal>malloc/free</literal>, but not quite as fast as
463 stack allocation in C. Use <literal>alloca</literal>
464 whenever you can.</para>
469 <term><literal>mallocForeignPtr</literal></term>
471 <para>Useful for longer-term allocation which requires
472 garbage collection. If you intend to store the pointer to
473 the memory in a foreign data structure, then
474 <literal>mallocForeignPtr</literal> is
475 <emphasis>not</emphasis> a good choice, however.</para>
477 <para>In GHC, <literal>mallocForeignPtr</literal> is also
478 implemented using <literal>MutableByteArray#</literal>.
479 Although the memory is pointed to by a
480 <literal>ForeignPtr</literal>, there are no actual
481 finalizers involved (unless you add one with
482 <literal>addForeignPtrFinalizer</literal>), and the
483 deallocation is done using GC, so
484 <literal>mallocForeignPtr</literal> is normally very
490 <term><literal>malloc/free</literal></term>
492 <para>If all else fails, then you need to resort to
493 <literal>Foreign.malloc</literal> and
494 <literal>Foreign.free</literal>. These are just wrappers
495 around the C functions of the same name, and their
496 efficiency will depend ultimately on the implementations
497 of these functions in your platform's C library. We
498 usually find <literal>malloc</literal> and
499 <literal>free</literal> to be significantly slower than
500 the other forms of allocation above.</para>
505 <term><literal>Foreign.Marshal.Pool</literal></term>
507 <para>Pools are currently implemented using
508 <literal>malloc/free</literal>, so while they might be a
509 more convenient way to structure your memory allocation
510 than using one of the other forms of allocation, they
511 won't be any more efficient. We do plan to provide an
512 improved-performance implementation of Pools in the
513 future, however.</para>
522 ;;; Local Variables: ***
524 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***