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.</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  -->