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>The FFI support in GHC diverges from the Addendum in the following ways:</para>
22 <para>Syntactic forms and library functions proposed in earlier versions
23 of the FFI are still supported for backwards compatibility.</para>
27 <para>GHC implements a number of GHC-specific extensions to the FFI
28 Addendum. These extensions are described in <xref linkend="ffi-ghcexts" />, but please note that programs using
29 these features are not portable. Hence, these features should be
30 avoided where possible.</para>
34 <para>The FFI libraries are documented in the accompanying library
35 documentation; see for example the <literal>Foreign</literal>
38 <sect1 id="ffi-ghcexts">
39 <title>GHC extensions to the FFI Addendum</title>
41 <para>The FFI features that are described in this section are specific to
42 GHC. Avoid them where possible to not compromise the portability of the
43 resulting code.</para>
46 <title>Unboxed types</title>
48 <para>The following unboxed types may be used as basic foreign types
49 (see FFI Addendum, Section 3.2): <literal>Int#</literal>,
50 <literal>Word#</literal>, <literal>Char#</literal>,
51 <literal>Float#</literal>, <literal>Double#</literal>,
52 <literal>Addr#</literal>, <literal>StablePtr# a</literal>,
53 <literal>MutableByteArray#</literal>, <literal>ForeignObj#</literal>,
54 and <literal>ByteArray#</literal>.</para>
57 <sect2 id="ffi-newtype-io">
58 <title>Newtype wrapping of the IO monad</title>
59 <para>The FFI spec requires the IO monad to appear in various places,
60 but it can sometimes be convenient to wrap the IO monad in a
61 <literal>newtype</literal>, thus:
63 newtype MyIO a = MIO (IO a)
65 (A reason for doing so might be to prevent the programmer from
66 calling arbitrary IO procedures in some part of the program.)
68 <para>The Haskell FFI already specifies that arguments and results of
69 foreign imports and exports will be automatically unwrapped if they are
70 newtypes (Section 3.2 of the FFI addendum). GHC extends the FFI by automatically unnwrapping any newtypes that
71 wrap the IO monad itself.
72 More precisely, wherever the FFI specification requires an IO type, GHC will
73 accept any newtype-wrapping of an IO type. For example, these declarations are
76 foreign import foo :: Int -> MyIO Int
77 foreign import "dynamic" baz :: (Int -> MyIO Int) -> CInt -> MyIO Int
85 <title>Using the FFI with GHC</title>
87 <para>The following sections also give some hints and tips on the
88 use of the foreign function interface in GHC.</para>
90 <sect2 id="foreign-export-ghc">
91 <title>Using <literal>foreign export</literal> and <literal>foreign import ccall "wrapper"</literal> with GHC</title>
93 <indexterm><primary><literal>foreign export
94 </literal></primary><secondary>with GHC</secondary>
97 <para>When GHC compiles a module (say <filename>M.hs</filename>)
98 which uses <literal>foreign export</literal> or
99 <literal>foreign import "wrapper"</literal>, it generates two
100 additional files, <filename>M_stub.c</filename> and
101 <filename>M_stub.h</filename>. GHC will automatically compile
102 <filename>M_stub.c</filename> to generate
103 <filename>M_stub.o</filename> at the same time.</para>
105 <para>For a plain <literal>foreign export</literal>, the file
106 <filename>M_stub.h</filename> contains a C prototype for the
107 foreign exported function, and <filename>M_stub.c</filename>
108 contains its definition. For example, if we compile the
109 following module:</para>
114 foreign export ccall foo :: Int -> IO Int
117 foo n = return (length (f n))
121 f n = n:(f (n-1))</programlisting>
123 <para>Then <filename>Foo_stub.h</filename> will contain
124 something like this:</para>
128 extern HsInt foo(HsInt a0);</programlisting>
130 <para>and <filename>Foo_stub.c</filename> contains the
131 compiler-generated definition of <literal>foo()</literal>. To
132 invoke <literal>foo()</literal> from C, just <literal>#include
133 "Foo_stub.h"</literal> and call <literal>foo()</literal>.</para>
135 <para>The <filename>foo_stub.c</filename> and
136 <filename>foo_stub.h</filename> files can be redirected using the
137 <option>-stubdir</option> option; see <xref linkend="options-output"
140 <sect3 id="using-own-main">
141 <title>Using your own <literal>main()</literal></title>
143 <para>Normally, GHC's runtime system provides a
144 <literal>main()</literal>, which arranges to invoke
145 <literal>Main.main</literal> in the Haskell program. However,
146 you might want to link some Haskell code into a program which
147 has a main function written in another language, say C. In
148 order to do this, you have to initialize the Haskell runtime
149 system explicitly.</para>
151 <para>Let's take the example from above, and invoke it from a
152 standalone C program. Here's the C code:</para>
155 #include <stdio.h>
158 #ifdef __GLASGOW_HASKELL__
159 #include "foo_stub.h"
162 #ifdef __GLASGOW_HASKELL__
163 extern void __stginit_Foo ( void );
166 int main(int argc, char *argv[])
170 hs_init(&argc, &argv);
171 #ifdef __GLASGOW_HASKELL__
172 hs_add_root(__stginit_Foo);
175 for (i = 0; i < 5; i++) {
176 printf("%d\n", foo(2500));
183 <para>We've surrounded the GHC-specific bits with
184 <literal>#ifdef __GLASGOW_HASKELL__</literal>; the rest of the
185 code should be portable across Haskell implementations that
186 support the FFI standard.</para>
188 <para>The call to <literal>hs_init()</literal>
189 initializes GHC's runtime system. Do NOT try to invoke any
190 Haskell functions before calling
191 <literal>hs_init()</literal>: strange things will
192 undoubtedly happen.</para>
194 <para>We pass <literal>argc</literal> and
195 <literal>argv</literal> to <literal>hs_init()</literal>
196 so that it can separate out any arguments for the RTS
197 (i.e. those arguments between
198 <literal>+RTS...-RTS</literal>).</para>
201 <function>hs_add_root</function><indexterm><primary><function>hs_add_root</function></primary>
202 </indexterm>, a GHC-specific interface which is required to
203 initialise the Haskell modules in the program. The argument
204 to <function>hs_add_root</function> should be the name of the
205 initialization function for the "root" module in your program
206 - in other words, the module which directly or indirectly
207 imports all the other Haskell modules in the program. In a
208 standalone Haskell program the root module is normally
209 <literal>Main</literal>, but when you are using Haskell code
210 from a library it may not be. If your program has multiple
211 root modules, then you can call
212 <function>hs_add_root</function> multiple times, one for each
213 root. The name of the initialization function for module
214 <replaceable>M</replaceable> is
215 <literal>__stginit_<replaceable>M</replaceable></literal>, and
216 it may be declared as an external function symbol as in the
217 code above. Note that the symbol name should be transformed
218 according to the Z-encoding:</para>
221 <tgroup cols="2" align="left" colsep="1" rowsep="1">
224 <entry>Character</entry>
225 <entry>Replacement</entry>
230 <entry><literal>.</literal></entry>
231 <entry><literal>zd</literal></entry>
234 <entry><literal>_</literal></entry>
235 <entry><literal>zu</literal></entry>
238 <entry><literal>`</literal></entry>
239 <entry><literal>zq</literal></entry>
242 <entry><literal>Z</literal></entry>
243 <entry><literal>ZZ</literal></entry>
246 <entry><literal>z</literal></entry>
247 <entry><literal>zz</literal></entry>
253 <para>After we've finished invoking our Haskell functions, we
254 can call <literal>hs_exit()</literal>, which
255 terminates the RTS. It runs any outstanding finalizers and
256 generates any profiling or stats output that might have been
259 <para>There can be multiple calls to
260 <literal>hs_init()</literal>, but each one should be matched
261 by one (and only one) call to
262 <literal>hs_exit()</literal><footnote><para>The outermost
263 <literal>hs_exit()</literal> will actually de-initialise the
264 system. NOTE that currently GHC's runtime cannot reliably
265 re-initialise after this has happened.</para>
268 <para>NOTE: when linking the final program, it is normally
269 easiest to do the link using GHC, although this isn't
270 essential. If you do use GHC, then don't forget the flag
271 <option>-no-hs-main</option><indexterm><primary><option>-no-hs-main</option></primary>
272 </indexterm>, otherwise GHC will try to link
273 to the <literal>Main</literal> Haskell module.</para>
276 <sect3 id="foreign-export-dynamic-ghc">
277 <title>Using <literal>foreign import ccall "wrapper"</literal> with GHC</title>
279 <indexterm><primary><literal>foreign import
280 ccall "wrapper"</literal></primary><secondary>with GHC</secondary>
283 <para>When <literal>foreign import ccall "wrapper"</literal> is used
284 in a Haskell module, The C stub file <filename>M_stub.c</filename>
285 generated by GHC contains small helper functions used by the code
286 generated for the imported wrapper, so it must be linked in to the
287 final program. When linking the program, remember to include
288 <filename>M_stub.o</filename> in the final link command line, or
289 you'll get link errors for the missing function(s) (this isn't
290 necessary when building your program with <literal>ghc
291 ––make</literal>, as GHC will automatically link in the
292 correct bits).</para>
296 <sect2 id="glasgow-foreign-headers">
297 <title>Using function headers</title>
299 <indexterm><primary>C calls, function headers</primary></indexterm>
301 <para>When generating C (using the <option>-fvia-C</option>
302 directive), one can assist the C compiler in detecting type
303 errors by using the <option>-#include</option> directive
304 (<xref linkend="options-C-compiler"/>) to provide
305 <filename>.h</filename> files containing function
308 <para>For example,</para>
313 void initialiseEFS (HsInt size);
314 HsInt terminateEFS (void);
315 HsForeignObj emptyEFS(void);
316 HsForeignObj updateEFS (HsForeignObj a, HsInt i, HsInt x);
317 HsInt lookupEFS (HsForeignObj a, HsInt i);
320 <para>The types <literal>HsInt</literal>,
321 <literal>HsForeignObj</literal> etc. are described in the H98 FFI
324 <para>Note that this approach is only
325 <emphasis>essential</emphasis> for returning
326 <literal>float</literal>s (or if <literal>sizeof(int) !=
327 sizeof(int *)</literal> on your architecture) but is a Good
328 Thing for anyone who cares about writing solid code. You're
329 crazy not to do it.</para>
332 What if you are importing a module from another package, and
333 a cross-module inlining exposes a foreign call that needs a supporting
334 <option>-#include</option>? If the imported module is from the same package as
335 the module being compiled, you should supply all the <option>-#include</option>
336 that you supplied when compiling the imported module. If the imported module comes
337 from another package, you won't necessarily know what the appropriate
338 <option>-#include</option> options are; but they should be in the package
339 configuration, which GHC knows about. So if you are building a package, remember
340 to put all those <option>-#include</option> options into the package configuration.
341 See the <literal>c_includes</literal> field in <xref linkend="package-management"/>.
345 It is also possible, according the FFI specification, to put the
346 <option>-#include</option> option in the foreign import
349 foreign import "foo.h f" f :: Int -> IO Int
351 When compiling this module, GHC will generate a C file that includes
352 the specified <option>-#include</option>. However, GHC
353 <emphasis>disables</emphasis> cross-module inlining for such foreign
354 calls, because it doesn't transport the <option>-#include</option>
355 information across module boundaries. (There is no fundamental reason for this;
356 it was just tiresome to implement. The wrapper, which unboxes the arguments
357 etc, is still inlined across modules.) So if you want the foreign call itself
358 to be inlined across modules, use the command-line and package-configuration
359 <option>-#include</option> mechanism.
362 <sect3 id="finding-header-files">
363 <title>Finding Header files</title>
365 <para>Header files named by the <option>-#include</option>
366 option or in a <literal>foreign import</literal> declaration
367 are searched for using the C compiler's usual search path.
368 You can add directories to this search path using the
369 <option>-I</option> option (see <xref
370 linkend="c-pre-processor"/>).</para>
372 <para>Note: header files are ignored unless compiling via C.
373 If you had been compiling your code using the native code
374 generator (the default) and suddenly switch to compiling via
375 C, then you can get unexpected errors about missing include
376 files. Compiling via C is enabled automatically when certain
377 options are given (eg. <option>-O</option> and
378 <option>-prof</option> both enable
379 <option>-fvia-C</option>).</para>
385 <title>Memory Allocation</title>
387 <para>The FFI libraries provide several ways to allocate memory
388 for use with the FFI, and it isn't always clear which way is the
389 best. This decision may be affected by how efficient a
390 particular kind of allocation is on a given compiler/platform,
391 so this section aims to shed some light on how the different
392 kinds of allocation perform with GHC.</para>
396 <term><literal>alloca</literal> and friends</term>
398 <para>Useful for short-term allocation when the allocation
399 is intended to scope over a given <literal>IO</literal>
400 computation. This kind of allocation is commonly used
401 when marshalling data to and from FFI functions.</para>
403 <para>In GHC, <literal>alloca</literal> is implemented
404 using <literal>MutableByteArray#</literal>, so allocation
405 and deallocation are fast: much faster than C's
406 <literal>malloc/free</literal>, but not quite as fast as
407 stack allocation in C. Use <literal>alloca</literal>
408 whenever you can.</para>
413 <term><literal>mallocForeignPtr</literal></term>
415 <para>Useful for longer-term allocation which requires
416 garbage collection. If you intend to store the pointer to
417 the memory in a foreign data structure, then
418 <literal>mallocForeignPtr</literal> is
419 <emphasis>not</emphasis> a good choice, however.</para>
421 <para>In GHC, <literal>mallocForeignPtr</literal> is also
422 implemented using <literal>MutableByteArray#</literal>.
423 Although the memory is pointed to by a
424 <literal>ForeignPtr</literal>, there are no actual
425 finalizers involved (unless you add one with
426 <literal>addForeignPtrFinalizer</literal>), and the
427 deallocation is done using GC, so
428 <literal>mallocForeignPtr</literal> is normally very
434 <term><literal>malloc/free</literal></term>
436 <para>If all else fails, then you need to resort to
437 <literal>Foreign.malloc</literal> and
438 <literal>Foreign.free</literal>. These are just wrappers
439 around the C functions of the same name, and their
440 efficiency will depend ultimately on the implementations
441 of these functions in your platform's C library. We
442 usually find <literal>malloc</literal> and
443 <literal>free</literal> to be significantly slower than
444 the other forms of allocation above.</para>
449 <term><literal>Foreign.Marshal.Pool</literal></term>
451 <para>Pools are currently implemented using
452 <literal>malloc/free</literal>, so while they might be a
453 more convenient way to structure your memory allocation
454 than using one of the other forms of allocation, they
455 won't be any more efficient. We do plan to provide an
456 improved-performance implementation of Pools in the
457 future, however.</para>
466 ;;; Local Variables: ***
468 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***