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="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="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="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.  Note that the symbol name should be transformed
 218         according to the Z-encoding:</para>
 219
 220       <informaltable>
 221         <tgroup cols="2" align="left" colsep="1" rowsep="1">
 222           <thead>
 223             <row>
 224               <entry>Character</entry>
 225               <entry>Replacement</entry>
 226             </row>
 227           </thead>
 228           <tbody>
 229             <row>
 230               <entry><literal>.</literal></entry>
 231               <entry><literal>zd</literal></entry>
 232             </row>
 233             <row>
 234               <entry><literal>_</literal></entry>
 235               <entry><literal>zu</literal></entry>
 236             </row>
 237             <row>
 238               <entry><literal>`</literal></entry>
 239               <entry><literal>zq</literal></entry>
 240             </row>
 241             <row>
 242               <entry><literal>Z</literal></entry>
 243               <entry><literal>ZZ</literal></entry>
 244             </row>
 245             <row>
 246               <entry><literal>z</literal></entry>
 247               <entry><literal>zz</literal></entry>
 248             </row>
 249           </tbody>
 250         </tgroup>
 251       </informaltable>
 252
 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
 257         requested.</para>
 258
 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>
 266         </footnote>.</para>
 267
 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>
 274       </sect3>
 275
 276       <sect3 id="foreign-export-dynamic-ghc">
 277         <title>Using <literal>foreign import ccall "wrapper"</literal> with GHC</title>
 278
 279         <indexterm><primary><literal>foreign import
 280         ccall "wrapper"</literal></primary><secondary>with GHC</secondary>
 281         </indexterm>
 282
 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         &ndash;&ndash;make</literal>, as GHC will automatically link in the
 292         correct bits).</para>
 293       </sect3>
 294     </sect2>
 295
 296     <sect2 id="glasgow-foreign-headers">
 297       <title>Using function headers</title>
 298
 299       <indexterm><primary>C calls, function headers</primary></indexterm>
 300
 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>-&num;include</option> directive
 304       (<xref linkend="options-C-compiler"/>) to provide
 305       <filename>.h</filename> files containing function
 306       headers.</para>
 307
 308       <para>For example,</para>
 309
 310 <programlisting>
 311 #include "HsFFI.h"
 312
 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);
 318 </programlisting>
 319
 320       <para>The types <literal>HsInt</literal>,
 321       <literal>HsForeignObj</literal> etc. are described in the H98 FFI
 322       Addendum.</para>
 323
 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>
 330
 331 <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>-&num;include</option>?  If the imported module is from the same package as
 335 the module being compiled, you should supply all the <option>-&num;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>-&num;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>-&num;include</option> options into the package configuration.
 341 See the <literal>c_includes</literal> field in <xref linkend="package-management"/>.
 342 </para>
 343
 344 <para>
 345 It is also possible, according the FFI specification, to put the
 346 <option>-&num;include</option> option in the foreign import
 347 declaration itself:
 348 <programlisting>
 349   foreign import "foo.h f" f :: Int -> IO Int
 350 </programlisting>
 351 When compiling this module, GHC will generate a C file that includes
 352 the specified <option>-&num;include</option>.  However, GHC
 353 <emphasis>disables</emphasis> cross-module inlining for such foreign
 354 calls, because it doesn't transport the <option>-&num;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>-&num;include</option> mechanism.
 360 </para>
 361
 362       <sect3 id="finding-header-files">
 363         <title>Finding Header files</title>
 364
 365         <para>Header files named by the <option>-&num;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>
 371
 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>
 380       </sect3>
 381
 382     </sect2>
 383
 384     <sect2>
 385       <title>Memory Allocation</title>
 386
 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>
 393
 394       <variablelist>
 395         <varlistentry>
 396           <term><literal>alloca</literal> and friends</term>
 397           <listitem>
 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>
 402
 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>
 409           </listitem>
 410         </varlistentry>
 411
 412         <varlistentry>
 413           <term><literal>mallocForeignPtr</literal></term>
 414           <listitem>
 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>
 420
 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
 429             cheap.</para>
 430           </listitem>
 431         </varlistentry>
 432
 433         <varlistentry>
 434           <term><literal>malloc/free</literal></term>
 435           <listitem>
 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>
 445           </listitem>
 446         </varlistentry>
 447
 448         <varlistentry>
 449           <term><literal>Foreign.Marshal.Pool</literal></term>
 450           <listitem>
 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>
 458           </listitem>
 459         </varlistentry>
 460       </variablelist>
 461     </sect2>
 462   </sect1>
 463 </chapter>
 464
 465 <!-- Emacs stuff:
 466      ;;; Local Variables: ***
 467      ;;; mode: xml ***
 468      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
 469      ;;; End: ***
 470  -->