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://www.haskell.org/"><literal>http://www.haskell.org/</literal></ulink>.</para>
  11
  12   <para>To enable FFI support in GHC, give the <option>-XForeignFunctionInterface</option><indexterm><primary><option>-XForeignFunctionInterface</option></primary>
  13     </indexterm> flag.</para>
  14
  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>
  19
  20   <para>The FFI libraries are documented in the accompanying library
  21   documentation; see for example the
  22     <ulink url="&libraryBaseLocation;/Control-Concurrent.html"><literal>Foreign</literal></ulink> module.</para>
  23
  24   <sect1 id="ffi-ghcexts">
  25     <title>GHC extensions to the FFI Addendum</title>
  26
  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>
  29
  30     <sect2>
  31       <title>Unboxed types</title>
  32
  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>
  40     </sect2>
  41
  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:
  47 <programlisting>
  48   newtype MyIO a = MIO (IO a)
  49 </programlisting>
  50      (A reason for doing so might be to prevent the programmer from
  51         calling arbitrary IO procedures in some part of the program.)
  52 </para>
  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
  59 OK:
  60 <programlisting>
  61    foreign import foo :: Int -> MyIO Int
  62    foreign import "dynamic" baz :: (Int -> MyIO Int) -> CInt -> MyIO Int
  63 </programlisting>
  64 </para>
  65       </sect2>
  66
  67       <sect2 id="ffi-prim">
  68         <title>Primitive imports</title>
  69         <para>
  70           GHC extends the FFI with an additional calling convention
  71           <literal>prim</literal>, e.g.:
  72 <programlisting>
  73    foreign import prim "foo" foo :: ByteArray# -> (# Int#, Int# #)
  74 </programlisting>
  75           This is used to import functions written in Cmm code that follow an
  76           internal GHC calling convention. This feature is not intended for
  77           use outside of the core libraries that come with GHC. For more
  78           details see the GHC developer wiki.
  79         </para>
  80       </sect2>
  81   </sect1>
  82
  83   <sect1 id="ffi-ghc">
  84     <title>Using the FFI with GHC</title>
  85
  86     <para>The following sections also give some hints and tips on the
  87     use of the foreign function interface in GHC.</para>
  88
  89     <sect2 id="foreign-export-ghc">
  90       <title>Using <literal>foreign export</literal> and <literal>foreign import ccall "wrapper"</literal> with GHC</title>
  91
  92       <indexterm><primary><literal>foreign export
  93       </literal></primary><secondary>with GHC</secondary>
  94       </indexterm>
  95
  96       <para>When GHC compiles a module (say <filename>M.hs</filename>)
  97       which uses <literal>foreign export</literal> or
  98       <literal>foreign import "wrapper"</literal>, it generates two
  99       additional files, <filename>M_stub.c</filename> and
 100       <filename>M_stub.h</filename>.  GHC will automatically compile
 101       <filename>M_stub.c</filename> to generate
 102       <filename>M_stub.o</filename> at the same time.</para>
 103
 104       <para>For a plain <literal>foreign export</literal>, the file
 105       <filename>M_stub.h</filename> contains a C prototype for the
 106       foreign exported function, and <filename>M_stub.c</filename>
 107       contains its definition.  For example, if we compile the
 108       following module:</para>
 109
 110 <programlisting>
 111 module Foo where
 112
 113 foreign export ccall foo :: Int -> IO Int
 114
 115 foo :: Int -> IO Int
 116 foo n = return (length (f n))
 117
 118 f :: Int -> [Int]
 119 f 0 = []
 120 f n = n:(f (n-1))</programlisting>
 121
 122       <para>Then <filename>Foo_stub.h</filename> will contain
 123       something like this:</para>
 124
 125 <programlisting>
 126 #include "HsFFI.h"
 127 extern HsInt foo(HsInt a0);</programlisting>
 128
 129       <para>and <filename>Foo_stub.c</filename> contains the
 130       compiler-generated definition of <literal>foo()</literal>.  To
 131       invoke <literal>foo()</literal> from C, just <literal>#include
 132       "Foo_stub.h"</literal> and call <literal>foo()</literal>.</para>
 133
 134       <para>The <filename>foo_stub.c</filename> and
 135         <filename>foo_stub.h</filename> files can be redirected using the
 136         <option>-stubdir</option> option; see <xref linkend="options-output"
 137           />.</para>
 138
 139       <para>When linking the program, remember to include
 140         <filename>M_stub.o</filename> in the final link command line, or
 141         you'll get link errors for the missing function(s) (this isn't
 142         necessary when building your program with <literal>ghc
 143         &ndash;&ndash;make</literal>, as GHC will automatically link in the
 144         correct bits).</para>
 145
 146       <sect3 id="using-own-main">
 147         <title>Using your own <literal>main()</literal></title>
 148
 149         <para>Normally, GHC's runtime system provides a
 150         <literal>main()</literal>, which arranges to invoke
 151         <literal>Main.main</literal> in the Haskell program.  However,
 152         you might want to link some Haskell code into a program which
 153         has a main function written in another language, say C.  In
 154         order to do this, you have to initialize the Haskell runtime
 155         system explicitly.</para>
 156
 157         <para>Let's take the example from above, and invoke it from a
 158         standalone C program.  Here's the C code:</para>
 159
 160 <programlisting>
 161 #include &lt;stdio.h&gt;
 162 #include "HsFFI.h"
 163
 164 #ifdef __GLASGOW_HASKELL__
 165 #include "foo_stub.h"
 166 #endif
 167
 168 #ifdef __GLASGOW_HASKELL__
 169 extern void __stginit_Foo ( void );
 170 #endif
 171
 172 int main(int argc, char *argv[])
 173 {
 174   int i;
 175
 176   hs_init(&amp;argc, &amp;argv);
 177 #ifdef __GLASGOW_HASKELL__
 178   hs_add_root(__stginit_Foo);
 179 #endif
 180
 181   for (i = 0; i &lt; 5; i++) {
 182     printf("%d\n", foo(2500));
 183   }
 184
 185   hs_exit();
 186   return 0;
 187 }</programlisting>
 188
 189         <para>We've surrounded the GHC-specific bits with
 190         <literal>#ifdef __GLASGOW_HASKELL__</literal>; the rest of the
 191         code should be portable across Haskell implementations that
 192         support the FFI standard.</para>
 193
 194         <para>The call to <literal>hs_init()</literal>
 195         initializes GHC's runtime system.  Do NOT try to invoke any
 196         Haskell functions before calling
 197         <literal>hs_init()</literal>: bad things will
 198         undoubtedly happen.</para>
 199
 200         <para>We pass references to <literal>argc</literal> and
 201         <literal>argv</literal> to <literal>hs_init()</literal>
 202         so that it can separate out any arguments for the RTS
 203         (i.e. those arguments between
 204         <literal>+RTS...-RTS</literal>).</para>
 205
 206         <para>Next, we call
 207         <function>hs_add_root</function><indexterm><primary><function>hs_add_root</function></primary>
 208         </indexterm>, a GHC-specific interface which is required to
 209         initialise the Haskell modules in the program.  The argument
 210         to <function>hs_add_root</function> should be the name of the
 211         initialization function for the "root" module in your program
 212         - in other words, the module which directly or indirectly
 213         imports all the other Haskell modules in the program.  In a
 214         standalone Haskell program the root module is normally
 215         <literal>Main</literal>, but when you are using Haskell code
 216         from a library it may not be.  If your program has multiple
 217         root modules, then you can call
 218         <function>hs_add_root</function> multiple times, one for each
 219         root.  The name of the initialization function for module
 220         <replaceable>M</replaceable> is
 221         <literal>__stginit_<replaceable>M</replaceable></literal>, and
 222         it may be declared as an external function symbol as in the
 223         code above.  Note that the symbol name should be transformed
 224         according to the Z-encoding:</para>
 225
 226       <informaltable>
 227         <tgroup cols="2" align="left" colsep="1" rowsep="1">
 228           <thead>
 229             <row>
 230               <entry>Character</entry>
 231               <entry>Replacement</entry>
 232             </row>
 233           </thead>
 234           <tbody>
 235             <row>
 236               <entry><literal>.</literal></entry>
 237               <entry><literal>zd</literal></entry>
 238             </row>
 239             <row>
 240               <entry><literal>_</literal></entry>
 241               <entry><literal>zu</literal></entry>
 242             </row>
 243             <row>
 244               <entry><literal>`</literal></entry>
 245               <entry><literal>zq</literal></entry>
 246             </row>
 247             <row>
 248               <entry><literal>Z</literal></entry>
 249               <entry><literal>ZZ</literal></entry>
 250             </row>
 251             <row>
 252               <entry><literal>z</literal></entry>
 253               <entry><literal>zz</literal></entry>
 254             </row>
 255           </tbody>
 256         </tgroup>
 257       </informaltable>
 258
 259         <para>After we've finished invoking our Haskell functions, we
 260         can call <literal>hs_exit()</literal>, which terminates the
 261         RTS.</para>
 262
 263         <para>There can be multiple calls to
 264         <literal>hs_init()</literal>, but each one should be matched
 265         by one (and only one) call to
 266         <literal>hs_exit()</literal><footnote><para>The outermost
 267         <literal>hs_exit()</literal> will actually de-initialise the
 268         system.  NOTE that currently GHC's runtime cannot reliably
 269         re-initialise after this has happened,
 270         see <xref linkend="ffi-divergence" />.</para>
 271         </footnote>.</para>
 272
 273         <para>NOTE: when linking the final program, it is normally
 274         easiest to do the link using GHC, although this isn't
 275         essential.  If you do use GHC, then don't forget the flag
 276         <option>-no-hs-main</option><indexterm><primary><option>-no-hs-main</option></primary>
 277           </indexterm>, otherwise GHC will try to link
 278         to the <literal>Main</literal> Haskell module.</para>
 279       </sect3>
 280
 281       <sect3 id="ffi-library">
 282         <title>Making a Haskell library that can be called from foreign
 283           code</title>
 284
 285         <para>The scenario here is much like in <xref linkend="using-own-main"
 286             />, except that the aim is not to link a complete program, but to
 287           make a library from Haskell code that can be deployed in the same
 288           way that you would deploy a library of C code.</para>
 289
 290         <para>The main requirement here is that the runtime needs to be
 291           initialized before any Haskell code can be called, so your library
 292           should provide initialisation and deinitialisation entry points,
 293           implemented in C or C++.  For example:</para>
 294
 295 <programlisting>
 296  HsBool mylib_init(void){
 297    int argc = ...
 298    char *argv[] = ...
 299
 300    // Initialize Haskell runtime
 301    hs_init(&amp;argc, &amp;argv);
 302
 303    // Tell Haskell about all root modules
 304    hs_add_root(__stginit_Foo);
 305
 306    // do any other initialization here and
 307    // return false if there was a problem
 308    return HS_BOOL_TRUE;
 309  }
 310
 311  void mylib_end(void){
 312    hs_exit();
 313  }
 314 </programlisting>
 315
 316         <para>The initialisation routine, <literal>mylib_init</literal>, calls
 317           <literal>hs_init()</literal> and <literal>hs_add_root()</literal> as
 318           normal to initialise the Haskell runtime, and the corresponding
 319           deinitialisation function <literal>mylib_end()</literal> calls
 320           <literal>hs_exit()</literal> to shut down the runtime.</para>
 321       </sect3>
 322
 323     </sect2>
 324
 325     <sect2 id="glasgow-foreign-headers">
 326       <title>Using header files</title>
 327
 328       <indexterm><primary>C calls, function headers</primary></indexterm>
 329
 330       <para>C functions are normally declared using prototypes in a C
 331         header file.  Earlier versions of GHC (6.8.3 and
 332         earlier) <literal>&num;include</literal>d the header file in
 333         the C source file generated from the Haskell code, and the C
 334         compiler could therefore check that the C function being
 335         called via the FFI was being called at the right type.</para>
 336
 337       <para>GHC no longer includes external header files when
 338         compiling via C, so this checking is not performed.  The
 339         change was made for compatibility with the native code backend
 340         (<literal>-fasm</literal>) and to comply strictly with the FFI
 341         specification, which requires that FFI calls are not subject
 342         to macro expansion and other CPP conversions that may be
 343         applied when using C header files.  This approach also
 344         simplifies the inlining of foreign calls across module and
 345         package boundaries: there's no need for the header file to be
 346         available when compiling an inlined version of a foreign call,
 347         so the compiler is free to inline foreign calls in any
 348         context.</para>
 349
 350       <para>The <literal>-&num;include</literal> option is now
 351         deprecated, and the <literal>include-files</literal> field
 352         in a Cabal package specification is ignored.</para>
 353
 354     </sect2>
 355
 356     <sect2>
 357       <title>Memory Allocation</title>
 358
 359       <para>The FFI libraries provide several ways to allocate memory
 360       for use with the FFI, and it isn't always clear which way is the
 361       best.  This decision may be affected by how efficient a
 362       particular kind of allocation is on a given compiler/platform,
 363       so this section aims to shed some light on how the different
 364       kinds of allocation perform with GHC.</para>
 365
 366       <variablelist>
 367         <varlistentry>
 368           <term><literal>alloca</literal> and friends</term>
 369           <listitem>
 370             <para>Useful for short-term allocation when the allocation
 371             is intended to scope over a given <literal>IO</literal>
 372             computation.  This kind of allocation is commonly used
 373             when marshalling data to and from FFI functions.</para>
 374
 375             <para>In GHC, <literal>alloca</literal> is implemented
 376             using <literal>MutableByteArray#</literal>, so allocation
 377             and deallocation are fast: much faster than C's
 378             <literal>malloc/free</literal>, but not quite as fast as
 379             stack allocation in C.  Use <literal>alloca</literal>
 380             whenever you can.</para>
 381           </listitem>
 382         </varlistentry>
 383
 384         <varlistentry>
 385           <term><literal>mallocForeignPtr</literal></term>
 386           <listitem>
 387             <para>Useful for longer-term allocation which requires
 388             garbage collection.  If you intend to store the pointer to
 389             the memory in a foreign data structure, then
 390             <literal>mallocForeignPtr</literal> is
 391             <emphasis>not</emphasis> a good choice, however.</para>
 392
 393             <para>In GHC, <literal>mallocForeignPtr</literal> is also
 394             implemented using <literal>MutableByteArray#</literal>.
 395             Although the memory is pointed to by a
 396             <literal>ForeignPtr</literal>, there are no actual
 397             finalizers involved (unless you add one with
 398             <literal>addForeignPtrFinalizer</literal>), and the
 399             deallocation is done using GC, so
 400             <literal>mallocForeignPtr</literal> is normally very
 401             cheap.</para>
 402           </listitem>
 403         </varlistentry>
 404
 405         <varlistentry>
 406           <term><literal>malloc/free</literal></term>
 407           <listitem>
 408             <para>If all else fails, then you need to resort to
 409             <literal>Foreign.malloc</literal> and
 410             <literal>Foreign.free</literal>.  These are just wrappers
 411             around the C functions of the same name, and their
 412             efficiency will depend ultimately on the implementations
 413             of these functions in your platform's C library.  We
 414             usually find <literal>malloc</literal> and
 415             <literal>free</literal> to be significantly slower than
 416             the other forms of allocation above.</para>
 417           </listitem>
 418         </varlistentry>
 419
 420         <varlistentry>
 421           <term><literal>Foreign.Marshal.Pool</literal></term>
 422           <listitem>
 423             <para>Pools are currently implemented using
 424             <literal>malloc/free</literal>, so while they might be a
 425             more convenient way to structure your memory allocation
 426             than using one of the other forms of allocation, they
 427             won't be any more efficient.  We do plan to provide an
 428             improved-performance implementation of Pools in the
 429             future, however.</para>
 430           </listitem>
 431         </varlistentry>
 432       </variablelist>
 433     </sect2>
 434
 435     <sect2 id="ffi-threads">
 436       <title>Multi-threading and the FFI</title>
 437
 438       <para>In order to use the FFI in a multi-threaded setting, you must
 439         use the <option>-threaded</option> option
 440         (see <xref linkend="options-linker" />).</para>
 441
 442       <sect3>
 443         <title>Foreign imports and multi-threading</title>
 444
 445         <para>When you call a <literal>foreign import</literal>ed
 446           function that is annotated as <literal>safe</literal> (the
 447           default), and the program was linked
 448           using <option>-threaded</option>, then the call will run
 449           concurrently with other running Haskell threads.  If the
 450           program was linked without <option>-threaded</option>,
 451           then the other Haskell threads will be blocked until the
 452           call returns.</para>
 453
 454         <para>This means that if you need to make a foreign call to
 455           a function that takes a long time or blocks indefinitely,
 456           then you should mark it <literal>safe</literal> and
 457           use <option>-threaded</option>.  Some library functions
 458           make such calls internally; their documentation should
 459           indicate when this is the case.</para>
 460
 461         <para>If you are making foreign calls from multiple Haskell
 462           threads and using <option>-threaded</option>, make sure that
 463           the foreign code you are calling is thread-safe.  In
 464           particularly, some GUI libraries are not thread-safe and
 465           require that the caller only invokes GUI methods from a
 466           single thread.  If this is the case, you may need to
 467           restrict your GUI operations to a single Haskell thread,
 468           and possibly also use a bound thread (see
 469           <xref linkend="haskell-threads-and-os-threads" />).</para>
 470
 471         <para>Note that foreign calls made by different Haskell
 472           threads may execute in <emphasis>parallel</emphasis>, even
 473           when the <literal>+RTS -N</literal> flag is not being used
 474           (<xref linkend="parallel-options" />).  The <literal>+RTS
 475           -N</literal> flag controls parallel execution of Haskell
 476           threads, but there may be an arbitrary number of foreign
 477           calls in progress at any one time, regardless of
 478           the <literal>+RTS -N</literal> value.</para>
 479       </sect3>
 480
 481       <sect3 id="haskell-threads-and-os-threads">
 482         <title>The relationship between Haskell threads and OS
 483           threads</title>
 484
 485         <para>Normally there is no fixed relationship between Haskell
 486           threads and OS threads.  This means that when you make a
 487           foreign call, that call may take place in an unspecified OS
 488           thread.  Furthermore, there is no guarantee that multiple
 489           calls made by one Haskell thread will be made by the same OS
 490           thread.</para>
 491
 492         <para>This usually isn't a problem, and it allows the GHC
 493           runtime system to make efficient use of OS thread resources.
 494           However, there are cases where it is useful to have more
 495           control over which OS thread is used, for example when
 496           calling foreign code that makes use of thread-local state.
 497           For cases like this, we provide <emphasis>bound
 498           threads</emphasis>, which are Haskell threads tied to a
 499           particular OS thread.  For information on bound threads, see
 500           the documentation
 501           for the <ulink url="&libraryBaseLocation;/Control-Concurrent.html"><literal>Control.Concurrent</literal></ulink>
 502           module.</para>
 503       </sect3>
 504
 505       <sect3>
 506         <title>Foreign exports and multi-threading</title>
 507
 508         <para>When the program is linked
 509           with <option>-threaded</option>, then you may
 510           invoke <literal>foreign export</literal>ed functions from
 511           multiple OS threads concurrently.  The runtime system must
 512           be initialised as usual by
 513           calling <literal>hs_init()</literal>
 514           and <literal>hs_add_root</literal>, and these calls must
 515           complete before invoking any <literal>foreign
 516           export</literal>ed functions.</para>
 517       </sect3>
 518
 519       <sect3 id="hs-exit">
 520         <title>On the use of <literal>hs_exit()</literal></title>
 521
 522         <para><literal>hs_exit()</literal> normally causes the termination of
 523           any running Haskell threads in the system, and when
 524           <literal>hs_exit()</literal> returns, there will be no more Haskell
 525           threads running.  The runtime will then shut down the system in an
 526           orderly way, generating profiling
 527           output and statistics if necessary, and freeing all the memory it
 528           owns.</para>
 529
 530         <para>It isn't always possible to terminate a Haskell thread forcibly:
 531           for example, the thread might be currently executing a foreign call,
 532           and we have no way to force the foreign call to complete.  What's
 533           more, the runtime must
 534           assume that in the worst case the Haskell code and runtime are about
 535           to be removed from memory (e.g. if this is a <link linkend="win32-dlls">Windows DLL</link>,
 536           <literal>hs_exit()</literal> is normally called before unloading the
 537           DLL).  So <literal>hs_exit()</literal> <emphasis>must</emphasis> wait
 538           until all outstanding foreign calls return before it can return
 539           itself.</para>
 540
 541         <para>The upshot of this is that if you have Haskell threads that are
 542           blocked in foreign calls, then <literal>hs_exit()</literal> may hang
 543           (or possibly busy-wait) until the calls return.  Therefore it's a
 544           good idea to make sure you don't have any such threads in the system
 545           when calling <literal>hs_exit()</literal>.  This includes any threads
 546           doing I/O, because I/O may (or may not, depending on the
 547           type of I/O and the platform) be implemented using blocking foreign
 548           calls.</para>
 549
 550         <para>The GHC runtime treats program exit as a special case, to avoid
 551           the need to wait for blocked threads when a standalone
 552           executable exits.  Since the program and all its threads are about to
 553           terminate at the same time that the code is removed from memory, it
 554           isn't necessary to ensure that the threads have exited first.
 555           (Unofficially, if you want to use this fast and loose version of
 556           <literal>hs_exit()</literal>, then call
 557           <literal>shutdownHaskellAndExit()</literal> instead).</para>
 558       </sect3>
 559     </sect2>
 560
 561   </sect1>
 562 </chapter>
 563
 564 <!-- Emacs stuff:
 565      ;;; Local Variables: ***
 566      ;;; mode: xml ***
 567      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
 568      ;;; End: ***
 569  -->