ghc/docs/users_guide/ffi-chap.sgml

   1 <!-- FFI docs as a chapter -->
   2
   3 <Chapter id="ffi">
   4 <Title>Foreign function interface (FFI)</Title>
   5
   6   <para>GHC (mostly) conforms to the Haskell 98 Foreign Function Interface
   7   Addendum 1.0, whose definition is available from <ULink
   8   URL="http://haskell.org/"><literal>http://haskell.org/</literal></ULink >.
   9   The FFI support in GHC diverges from the Addendum in the following ways:
  10   </para>
  11
  12   <itemizedlist>
  13     <listitem>
  14       <para>The routines <literal>hs_init()</literal>,
  15       <literal>hs_exit()</literal>, and <literal>hs_set_argv()</literal> from
  16       Chapter 6.1 of the Addendum are not supported yet.</para>
  17     </listitem>
  18
  19     <listitem>
  20       <para>Syntactic forms and library functions proposed in earlier versions
  21       of the FFI are still supported for backwards compatibility.</para>
  22     </listitem>
  23
  24     <listitem>
  25       <para>GHC implements a number of GHC-specific extensions to the FFI
  26       Addendum.  These extensions are described in <xref
  27       linkend="sec-ffi-ghcexts">, but please note that programs using
  28       these features are not portable.  Hence, these features should be
  29       avoided where possible.</para>
  30     </listitem>
  31   </itemizedlist>
  32
  33   <para>The FFI libraries are documented in the accompanying library
  34   documentation; see for example the <literal>Foreign</literal>
  35   module.</para>
  36
  37   <sect1 id="sec-ffi-ghcexts">
  38     <title>GHC extensions to the FFI Addendum</title>
  39
  40     <para>The FFI features that are described in this section are specific to
  41     GHC.  Avoid them where possible to not compromise the portability of the
  42     resulting code.</para>
  43
  44     <sect2>
  45       <title>Unboxed types</title>
  46
  47       <para>The following unboxed types may be used as basic foreign types
  48       (see FFI Addendum, Section 3.2): <literal>Int#</literal>,
  49       <literal>Word#</literal>, <literal>Char#</literal>,
  50       <literal>Float#</literal>, <literal>Double#</literal>,
  51       <literal>Addr#</literal>, <literal>StablePtr# a</literal>,
  52       <literal>MutableByteArray#</literal>, <literal>ForeignObj#</literal>,
  53       and <literal>ByteArray#</literal>.</para>
  54     </sect2>
  55
  56   </sect1>
  57
  58   <sect1 id="sec-ffi-ghc">
  59     <title>Using the FFI with GHC</title>
  60
  61     <para>The following sections also give some hints and tips on the
  62     use of the foreign function interface in GHC.</para>
  63
  64     <sect2 id="foreign-export-ghc">
  65       <title>Using <literal>foreign export</literal> and <literal>foreign
  66       import ccall "wrapper"</literal> with GHC</title>
  67
  68       <indexterm><primary><literal>foreign export
  69       </literal></primary><secondary>with GHC</secondary>
  70       </indexterm>
  71
  72       <para>When GHC compiles a module (say <filename>M.hs</filename>)
  73       which uses <literal>foreign export</literal> or <literal>foreign
  74       import "wrapper"</literal>, it generates two
  75       additional files, <filename>M_stub.c</filename> and
  76       <filename>M_stub.h</filename>.  GHC will automatically compile
  77       <filename>M_stub.c</filename> to generate
  78       <filename>M_stub.o</filename> at the same time.</para>
  79
  80       <para>For a plain <literal>foreign export</literal>, the file
  81       <filename>M_stub.h</filename> contains a C prototype for the
  82       foreign exported function, and <filename>M_stub.c</filename>
  83       contains its definition.  For example, if we compile the
  84       following module:</para>
  85
  86 <programlisting>
  87 module Foo where
  88
  89 foreign export ccall foo :: Int -> IO Int
  90
  91 foo :: Int -> IO Int
  92 foo n = return (length (f n))
  93
  94 f :: Int -> [Int]
  95 f 0 = []
  96 f n = n:(f (n-1))</programlisting>
  97
  98       <para>Then <filename>Foo_stub.h</filename> will contain
  99       something like this:</para>
 100
 101 <programlisting>
 102 #include "HsFFI.h"
 103 extern HsInt foo(HsInt a0);</programlisting>
 104
 105       <para>and <filename>Foo_stub.c</filename> contains the
 106       compiler-generated definition of <literal>foo()</literal>.  To
 107       invoke <literal>foo()</literal> from C, just <literal>#include
 108       "Foo_stub.h"</literal> and call <literal>foo()</literal>.</para>
 109
 110       <sect3>
 111         <title>Using your own <literal>main()</literal></title>
 112
 113         <para>Normally, GHC's runtime system provides a
 114         <literal>main()</literal>, which arranges to invoke
 115         <literal>Main.main</literal> in the Haskell program.  However,
 116         you might want to link some Haskell code into a program which
 117         has a main function written in another languagem, say C.  In
 118         order to do this, you have to initialize the Haskell runtime
 119         system explicitly.</para>
 120
 121         <para>Let's take the example from above, and invoke it from a
 122         standalone C program.  Here's the C code:</para>
 123
 124 <programlisting>
 125 #include &lt;stdio.h&gt;
 126 #include "HsFFI.h"
 127
 128 #ifdef __GLASGOW_HASKELL__
 129 #include "foo_stub.h"
 130 #endif
 131
 132 #ifdef __GLASGOW_HASKELL__
 133 extern void __stginit_Foo ( void );
 134 #endif
 135
 136 int main(int argc, char *argv[])
 137 {
 138   int i;
 139
 140   hs_init(&amp;argc, &amp;argv);
 141 #ifdef __GLASGOW_HASKELL__
 142   hs_add_root(__stginit_Foo);
 143 #endif
 144
 145   for (i = 0; i < 5; i++) {
 146     printf("%d\n", foo(2500));
 147   }
 148
 149   hs_exit();
 150   return 0;
 151 }</programlisting>
 152
 153         <para>We've surrounded the GHC-specific bits with
 154         <literal>#ifdef __GLASGOW_HASKELL__</literal>; the rest of the
 155         code should be portable across Haskell implementations that
 156         support the FFI standard.</para>
 157
 158         <para>The call to <literal>hs_init()</literal>
 159         initializes GHC's runtime system.  Do NOT try to invoke any
 160         Haskell functions before calling
 161         <literal>hs_init()</literal>: strange things will
 162         undoubtedly happen.</para>
 163
 164         <para>We pass <literal>argc</literal> and
 165         <literal>argv</literal> to <literal>hs_init()</literal>
 166         so that it can separate out any arguments for the RTS
 167         (i.e. those arguments between
 168         <literal>+RTS...-RTS</literal>).</para>
 169
 170         <para>Next, we call
 171         <function>hs_add_root</function><indexterm><primary><function>hs_add_root</function></primary>
 172         </indexterm>, a GHC-specific interface which is required to
 173         initialise the Haskell modules in the program.  The argument
 174         to <function>hs_add_root</function> should be the name of the
 175         initialization function for the "root" module in your program
 176         - in other words, the module which directly or indirectly
 177         imports all the other Haskell modules in the program.  In a
 178         standalone Haskell program the root module is normally
 179         <literal>Main</literal>, but when you are using Haskell code
 180         from a library it may not be.  If your program has multiple
 181         root modules, then you can call
 182         <function>hs_add_root</function> multiple times, one for each
 183         root.  The name of the initialization function for module
 184         <replaceable>M</replaceable> is
 185         <literal>__stginit_<replaceable>M</replaceable></literal>, and
 186         it may be declared as an external function symbol as in the
 187         code above.</para>
 188
 189         <para>After we've finished invoking our Haskell functions, we
 190         can call <literal>hs_exit()</literal>, which
 191         terminates the RTS.  It runs any outstanding finalizers and
 192         generates any profiling or stats output that might have been
 193         requested.</para>
 194
 195         <para>There can be multiple calls to
 196         <literal>hs_init()</literal>, but each one should be matched
 197         by one (and only one) call to
 198         <literal>hs_exit()</literal><footnote><para>The outermost
 199         <literal>hs_exit()</literal> will actually de-initialise the
 200         system.  NOTE that currently GHC's runtime cannot reliably
 201         re-initialise after this has happened.</para>
 202         </footnote>.</para>
 203
 204         <para>NOTE: when linking the final program, it is normally
 205         easiest to do the link using GHC, although this isn't
 206         essential.  If you do use GHC, then don't forget the flag
 207         <option>-no-hs-main</option><indexterm><primary><option>-no-hs-main</option></primary>
 208           </indexterm>, otherwise GHC will try to link
 209         to the <literal>Main</literal> Haskell module.</para>
 210       </sect3>
 211
 212       <sect3 id="foreign-export-dynamic-ghc">
 213         <title>Using <literal>foreign import ccall "wrapper"</literal> with
 214         GHC</title>
 215
 216         <indexterm><primary><literal>foreign import
 217         ccall "wrapper"</literal></primary><secondary>with GHC</secondary>
 218         </indexterm>
 219
 220         <para>When <literal>foreign import ccall "wrapper"</literal> is used
 221         in a Haskell module, The C stub file <filename>M_stub.c</filename>
 222         generated by GHC contains small helper functions used by the code
 223         generated for the imported wrapper, so it must be linked in to the
 224         final program.  When linking the program, remember to include
 225         <filename>M_stub.o</filename> in the final link command line, or
 226         you'll get link errors for the missing function(s) (this isn't
 227         necessary when building your program with <literal>ghc
 228         &ndash;&ndash;make</literal>, as GHC will automatically link in the
 229         correct bits).</para>
 230       </sect3>
 231     </sect2>
 232
 233     <sect2 id="glasgow-foreign-headers">
 234       <title>Using function headers</title>
 235
 236       <indexterm><primary>C calls, function headers</primary></indexterm>
 237
 238       <para>When generating C (using the <option>-fvia-C</option>
 239       directive), one can assist the C compiler in detecting type
 240       errors by using the <option>-&num;include</option> directive
 241       (<xref linkend="options-C-compiler">) to provide
 242       <filename>.h</filename> files containing function
 243       headers.</para>
 244
 245       <para>For example,</para>
 246
 247 <programlisting>
 248 #include "HsFFI.h"
 249
 250 void         initialiseEFS (HsInt size);
 251 HsInt        terminateEFS (void);
 252 HsForeignObj emptyEFS(void);
 253 HsForeignObj updateEFS (HsForeignObj a, HsInt i, HsInt x);
 254 HsInt        lookupEFS (HsForeignObj a, HsInt i);
 255 </programlisting>
 256
 257       <para>The types <literal>HsInt</literal>,
 258       <literal>HsForeignObj</literal> etc. are described in the H98 FFI
 259       Addendum.</para>
 260
 261       <para>Note that this approach is only
 262       <emphasis>essential</emphasis> for returning
 263       <literal>float</literal>s (or if <literal>sizeof(int) !=
 264       sizeof(int *)</literal> on your architecture) but is a Good
 265       Thing for anyone who cares about writing solid code.  You're
 266       crazy not to do it.</para>
 267
 268 <para>
 269 What if you are importing a module from another package, and
 270 a cross-module inlining exposes a foreign call that needs a supporting
 271 <option>-&num;include</option>?  If the imported module is from the same package as
 272 the module being compiled, you should supply all the <option>-&num;include</option>
 273 that you supplied when compiling the imported module.  If the imported module comes
 274 from another package, you won't necessarily know what the appropriate
 275 <option>-&num;include</option> options are; but they should be in the package
 276 configuration, which GHC knows about.  So if you are building a package, remember
 277 to put all those <option>-&num;include</option> options into the package configuration.
 278 See the <literal>c_includes</literal> field in <xref linkend="package-management">.
 279 </para>
 280
 281 <para>
 282 It is also possible, according the FFI specification, to put the
 283 <option>-&num;include</option> option in the foreign import
 284 declaration itself:
 285 <programlisting>
 286   foreign import "foo.h f" f :: Int -> IO Int
 287 </programlisting>
 288 When compiling this module, GHC will generate a C file that includes
 289 the specified <option>-&num;include</option>.  However, GHC
 290 <emphasis>disables</emphasis> cross-module inlinding for such foreign
 291 calls, because it doesn't transport the <option>-&num;include</option>
 292 information across module boundaries.  (There is no fundamental reason for this;
 293 it was just tiresome to implement.  The wrapper, which unboxes the arguments
 294 etc, is still inlined across modules.)  So if you want the foreign call itself
 295 to be inlined across modules, use the command-line and package-configuration
 296 <option>-&num;include</option> mechanism.
 297 </para>
 298
 299     </sect2>
 300
 301     <sect2>
 302       <title>Memory Allocation</title>
 303
 304       <para>The FFI libraries provide several ways to allocate memory
 305       for use with the FFI, and it isn't always clear which way is the
 306       best.  This decision may be affected by how efficient a
 307       particular kind of allocation is on a given compiler/platform,
 308       so this section aims to shed some light on how the different
 309       kinds of allocation perform with GHC.</para>
 310
 311       <variablelist>
 312         <varlistentry>
 313           <term><literal>alloca</literal> and friends</term>
 314           <listitem>
 315             <para>Useful for short-term allocation when the allocation
 316             is intended to scope over a given <literal>IO</literal>
 317             compuatation.  This kind of allocation is commonly used
 318             when marshalling data to and from FFI functions.</para>
 319
 320             <para>In GHC, <literal>alloca</literal> is implemented
 321             using <literal>MutableByteArray#</literal>, so allocation
 322             and deallocation are fast: much faster than C's
 323             <literal>malloc/free</literal>, but not quite as fast as
 324             stack allocation in C.  Use <literal>alloca</literal>
 325             whenever you can.</para>
 326           </listitem>
 327         </varlistentry>
 328
 329         <varlistentry>
 330           <term><literal>mallocForeignPtr</literal></term>
 331           <listitem>
 332             <para>Useful for longer-term allocation which requires
 333             garbage collection.  If you intend to store the pointer to
 334             the memory in a foreign data structure, then
 335             <literal>mallocForeignPtr</literal> is
 336             <emphasis>not</emphasis> a good choice, however.</para>
 337
 338             <para>In GHC, <literal>mallocForeignPtr</literal> is also
 339             implemented using <literal>MutableByteArray#</literal>.
 340             Although the memory is pointed to by a
 341             <literal>ForeignPtr</literal>, there are no actual
 342             finalizers involved (unless you add one with
 343             <literal>addForeignPtrFinalizer</literal>), and the
 344             deallocation is done using GC, so
 345             <literal>mallocForeignPtr</literal> is normally very
 346             cheap.</para>
 347           </listitem>
 348         </varlistentry>
 349
 350         <varlistentry>
 351           <term><literal>malloc/free</literal></term>
 352           <listitem>
 353             <para>If all else fails, then you need to resort to
 354             <literal>Foreign.malloc</literal> and
 355             <literal>Foreign.free</literal>.  These are just wrappers
 356             around the C funcitons of the same name, and their
 357             efficiency will depend ultimately on the implementations
 358             of these functions in your platform's C library.  We
 359             usually find <literal>malloc</literal> and
 360             <literal>free</literal> to be significantly slower than
 361             the other forms of allocation above.</para>
 362           </listitem>
 363         </varlistentry>
 364
 365         <varlistentry>
 366           <term><literal>Foreign.Marhsal.Pool</literal></term>
 367           <listitem>
 368             <para>Pools are currently implemented using
 369             <literal>malloc/free</literal>, so while they might be a
 370             more convenient way to structure your memory allocation
 371             than using one of the other forms of allocation, they
 372             won't be any more efficient.  We do plan to provide an
 373             improved-performance implementaiton of Pools in the
 374             future, however.</para>
 375           </listitem>
 376         </varlistentry>
 377       </variablelist>
 378     </sect2>
 379   </sect1>
 380 </Chapter>
 381
 382 <!-- Emacs stuff:
 383      ;;; Local Variables: ***
 384      ;;; mode: sgml ***
 385      ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
 386      ;;; End: ***
 387  -->