Rearrange docs to have all the -ddump-* options together
[ghc-hetmet.git] / docs / users_guide / ffi-chap.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!-- FFI docs as a chapter -->
3
4 <chapter id="ffi">
5  <title>
6 Foreign function interface (FFI)
7  </title>
8
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>
11
12   <para>To enable FFI support in GHC, give the <option>-fffi</option><indexterm><primary><option>-fffi</option></primary>
13     </indexterm>flag, or
14 the <option>-fglasgow-exts</option><indexterm><primary><option>-fglasgow-exts</option></primary>
15     </indexterm> flag which implies <option>-fffi</option>
16 .</para>
17
18   <para>The FFI support in GHC diverges from the Addendum in the following ways:</para>
19
20   <itemizedlist>
21     <listitem>
22       <para>Syntactic forms and library functions proposed in earlier versions
23       of the FFI are still supported for backwards compatibility.</para>
24     </listitem>
25
26     <listitem>
27       <para>GHC implements a number of GHC-specific extensions to the FFI
28       Addendum.  These extensions are described in <xref linkend="sec-ffi-ghcexts" />, but please note that programs using
29       these features are not portable.  Hence, these features should be
30       avoided where possible.</para>
31     </listitem>
32   </itemizedlist>
33
34   <para>The FFI libraries are documented in the accompanying library
35   documentation; see for example the <literal>Foreign</literal>
36   module.</para>
37
38   <sect1 id="sec-ffi-ghcexts">
39     <title>GHC extensions to the FFI Addendum</title>
40
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>
44
45     <sect2>
46       <title>Unboxed types</title>
47
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>
55     </sect2>
56
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:
62 <programlisting>
63   newtype MyIO a = MIO (IO a)
64 </programlisting>
65      (A reason for doing so might be to prevent the programmer from
66         calling arbitrary IO procedures in some part of the program.)
67 </para>
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
74 OK:
75 <programlisting>
76    foreign import foo :: Int -> MyIO Int
77    foreign import "dynamic" baz :: (Int -> MyIO Int) -> CInt -> MyIO Int
78 </programlisting>
79 </para>
80       </sect2>
81
82   </sect1>
83
84   <sect1 id="sec-ffi-ghc">
85     <title>Using the FFI with GHC</title>
86
87     <para>The following sections also give some hints and tips on the
88     use of the foreign function interface in GHC.</para>
89
90     <sect2 id="foreign-export-ghc">
91       <title>Using <literal>foreign export</literal> and <literal>foreign import ccall "wrapper"</literal> with GHC</title>
92
93       <indexterm><primary><literal>foreign export
94       </literal></primary><secondary>with GHC</secondary>
95       </indexterm>
96
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>
104
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>
110
111 <programlisting>
112 module Foo where
113
114 foreign export ccall foo :: Int -> IO Int
115
116 foo :: Int -> IO Int
117 foo n = return (length (f n))
118
119 f :: Int -> [Int]
120 f 0 = []
121 f n = n:(f (n-1))</programlisting>
122
123       <para>Then <filename>Foo_stub.h</filename> will contain
124       something like this:</para>
125
126 <programlisting>
127 #include "HsFFI.h"
128 extern HsInt foo(HsInt a0);</programlisting>
129
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>
134
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"
138           />.</para>
139
140       <sect3 id="using-own-main"> 
141         <title>Using your own <literal>main()</literal></title>
142
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>
150
151         <para>Let's take the example from above, and invoke it from a
152         standalone C program.  Here's the C code:</para>
153
154 <programlisting>
155 #include &lt;stdio.h&gt;
156 #include "HsFFI.h"
157
158 #ifdef __GLASGOW_HASKELL__
159 #include "foo_stub.h"
160 #endif
161
162 #ifdef __GLASGOW_HASKELL__
163 extern void __stginit_Foo ( void );
164 #endif
165
166 int main(int argc, char *argv[])
167 {
168   int i;
169
170   hs_init(&amp;argc, &amp;argv);
171 #ifdef __GLASGOW_HASKELL__
172   hs_add_root(__stginit_Foo);
173 #endif
174
175   for (i = 0; i &lt; 5; i++) {
176     printf("%d\n", foo(2500));
177   }
178
179   hs_exit();
180   return 0;
181 }</programlisting>
182
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>
187
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>
193
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>
199
200         <para>Next, we call
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.</para>
218
219         <para>After we've finished invoking our Haskell functions, we
220         can call <literal>hs_exit()</literal>, which
221         terminates the RTS.  It runs any outstanding finalizers and
222         generates any profiling or stats output that might have been
223         requested.</para>
224
225         <para>There can be multiple calls to
226         <literal>hs_init()</literal>, but each one should be matched
227         by one (and only one) call to
228         <literal>hs_exit()</literal><footnote><para>The outermost
229         <literal>hs_exit()</literal> will actually de-initialise the
230         system.  NOTE that currently GHC's runtime cannot reliably
231         re-initialise after this has happened.</para>
232         </footnote>.</para>
233
234         <para>NOTE: when linking the final program, it is normally
235         easiest to do the link using GHC, although this isn't
236         essential.  If you do use GHC, then don't forget the flag
237         <option>-no-hs-main</option><indexterm><primary><option>-no-hs-main</option></primary>
238           </indexterm>, otherwise GHC will try to link
239         to the <literal>Main</literal> Haskell module.</para>
240       </sect3>
241
242       <sect3 id="foreign-export-dynamic-ghc">
243         <title>Using <literal>foreign import ccall "wrapper"</literal> with GHC</title>
244
245         <indexterm><primary><literal>foreign import
246         ccall "wrapper"</literal></primary><secondary>with GHC</secondary>
247         </indexterm>
248
249         <para>When <literal>foreign import ccall "wrapper"</literal> is used
250         in a Haskell module, The C stub file <filename>M_stub.c</filename>
251         generated by GHC contains small helper functions used by the code
252         generated for the imported wrapper, so it must be linked in to the
253         final program.  When linking the program, remember to include
254         <filename>M_stub.o</filename> in the final link command line, or
255         you'll get link errors for the missing function(s) (this isn't
256         necessary when building your program with <literal>ghc
257         &ndash;&ndash;make</literal>, as GHC will automatically link in the
258         correct bits).</para>
259       </sect3>
260     </sect2>
261     
262     <sect2 id="glasgow-foreign-headers">
263       <title>Using function headers</title>
264
265       <indexterm><primary>C calls, function headers</primary></indexterm>
266
267       <para>When generating C (using the <option>-fvia-C</option>
268       directive), one can assist the C compiler in detecting type
269       errors by using the <option>-&num;include</option> directive
270       (<xref linkend="options-C-compiler"/>) to provide
271       <filename>.h</filename> files containing function
272       headers.</para>
273
274       <para>For example,</para>
275
276 <programlisting>
277 #include "HsFFI.h"
278
279 void         initialiseEFS (HsInt size);
280 HsInt        terminateEFS (void);
281 HsForeignObj emptyEFS(void);
282 HsForeignObj updateEFS (HsForeignObj a, HsInt i, HsInt x);
283 HsInt        lookupEFS (HsForeignObj a, HsInt i);
284 </programlisting>
285
286       <para>The types <literal>HsInt</literal>,
287       <literal>HsForeignObj</literal> etc. are described in the H98 FFI
288       Addendum.</para>
289
290       <para>Note that this approach is only
291       <emphasis>essential</emphasis> for returning
292       <literal>float</literal>s (or if <literal>sizeof(int) !=
293       sizeof(int *)</literal> on your architecture) but is a Good
294       Thing for anyone who cares about writing solid code.  You're
295       crazy not to do it.</para>
296
297 <para>
298 What if you are importing a module from another package, and
299 a cross-module inlining exposes a foreign call that needs a supporting
300 <option>-&num;include</option>?  If the imported module is from the same package as
301 the module being compiled, you should supply all the <option>-&num;include</option>
302 that you supplied when compiling the imported module.  If the imported module comes
303 from another package, you won't necessarily know what the appropriate 
304 <option>-&num;include</option> options are; but they should be in the package 
305 configuration, which GHC knows about.  So if you are building a package, remember
306 to put all those <option>-&num;include</option> options into the package configuration.
307 See the <literal>c_includes</literal> field in <xref linkend="package-management"/>.
308 </para>
309
310 <para>
311 It is also possible, according the FFI specification, to put the 
312 <option>-&num;include</option> option in the foreign import 
313 declaration itself:
314 <programlisting>
315   foreign import "foo.h f" f :: Int -> IO Int
316 </programlisting>
317 When compiling this module, GHC will generate a C file that includes
318 the specified <option>-&num;include</option>.  However, GHC
319 <emphasis>disables</emphasis> cross-module inlining for such foreign
320 calls, because it doesn't transport the <option>-&num;include</option>
321 information across module boundaries.  (There is no fundamental reason for this;
322 it was just tiresome to implement.  The wrapper, which unboxes the arguments
323 etc, is still inlined across modules.)  So if you want the foreign call itself
324 to be inlined across modules, use the command-line and package-configuration
325 <option>-&num;include</option> mechanism.
326 </para>
327
328       <sect3 id="finding-header-files">
329         <title>Finding Header files</title>
330
331         <para>Header files named by the <option>-&num;include</option>
332         option or in a <literal>foreign import</literal> declaration
333         are searched for using the C compiler's usual search path.
334         You can add directories to this search path using the
335         <option>-I</option> option (see <xref
336         linkend="c-pre-processor"/>).</para>
337
338         <para>Note: header files are ignored unless compiling via C.
339         If you had been compiling your code using the native code
340         generator (the default) and suddenly switch to compiling via
341         C, then you can get unexpected errors about missing include
342         files.  Compiling via C is enabled automatically when certain
343         options are given (eg. <option>-O</option> and
344         <option>-prof</option> both enable
345         <option>-fvia-C</option>).</para>
346       </sect3>
347
348     </sect2>
349
350     <sect2>
351       <title>Memory Allocation</title>
352
353       <para>The FFI libraries provide several ways to allocate memory
354       for use with the FFI, and it isn't always clear which way is the
355       best.  This decision may be affected by how efficient a
356       particular kind of allocation is on a given compiler/platform,
357       so this section aims to shed some light on how the different
358       kinds of allocation perform with GHC.</para>
359
360       <variablelist>
361         <varlistentry>
362           <term><literal>alloca</literal> and friends</term>
363           <listitem>
364             <para>Useful for short-term allocation when the allocation
365             is intended to scope over a given <literal>IO</literal>
366             computation.  This kind of allocation is commonly used
367             when marshalling data to and from FFI functions.</para>
368
369             <para>In GHC, <literal>alloca</literal> is implemented
370             using <literal>MutableByteArray#</literal>, so allocation
371             and deallocation are fast: much faster than C's
372             <literal>malloc/free</literal>, but not quite as fast as
373             stack allocation in C.  Use <literal>alloca</literal>
374             whenever you can.</para>
375           </listitem>
376         </varlistentry>
377
378         <varlistentry>
379           <term><literal>mallocForeignPtr</literal></term>
380           <listitem>
381             <para>Useful for longer-term allocation which requires
382             garbage collection.  If you intend to store the pointer to
383             the memory in a foreign data structure, then
384             <literal>mallocForeignPtr</literal> is
385             <emphasis>not</emphasis> a good choice, however.</para>
386
387             <para>In GHC, <literal>mallocForeignPtr</literal> is also
388             implemented using <literal>MutableByteArray#</literal>.
389             Although the memory is pointed to by a
390             <literal>ForeignPtr</literal>, there are no actual
391             finalizers involved (unless you add one with
392             <literal>addForeignPtrFinalizer</literal>), and the
393             deallocation is done using GC, so
394             <literal>mallocForeignPtr</literal> is normally very
395             cheap.</para>
396           </listitem>
397         </varlistentry>
398
399         <varlistentry>
400           <term><literal>malloc/free</literal></term>
401           <listitem>
402             <para>If all else fails, then you need to resort to
403             <literal>Foreign.malloc</literal> and
404             <literal>Foreign.free</literal>.  These are just wrappers
405             around the C functions of the same name, and their
406             efficiency will depend ultimately on the implementations
407             of these functions in your platform's C library.  We
408             usually find <literal>malloc</literal> and
409             <literal>free</literal> to be significantly slower than
410             the other forms of allocation above.</para>
411           </listitem>
412         </varlistentry>
413
414         <varlistentry>
415           <term><literal>Foreign.Marshal.Pool</literal></term>
416           <listitem>
417             <para>Pools are currently implemented using
418             <literal>malloc/free</literal>, so while they might be a
419             more convenient way to structure your memory allocation
420             than using one of the other forms of allocation, they
421             won't be any more efficient.  We do plan to provide an
422             improved-performance implementation of Pools in the
423             future, however.</para>
424           </listitem>
425         </varlistentry>
426       </variablelist>
427     </sect2>
428   </sect1>
429 </chapter>
430
431 <!-- Emacs stuff:
432      ;;; Local Variables: ***
433      ;;; mode: xml ***
434      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
435      ;;; End: ***
436  -->