+++ /dev/null
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- FFI docs as a chapter -->
-
-<chapter id="ffi">
- <title>
-Foreign function interface (FFI)
- </title>
-
- <para>GHC (mostly) conforms to the Haskell 98 Foreign Function Interface
- Addendum 1.0, whose definition is available from <ulink url="http://haskell.org/"><literal>http://haskell.org/</literal></ulink>.</para>
-
- <para>To enable FFI support in GHC, give the <option>-fffi</option><indexterm><primary><option>-fffi</option></primary>
- </indexterm>flag, or
-the <option>-fglasgow-exts</option><indexterm><primary><option>-fglasgow-exts</option></primary>
- </indexterm> flag which implies <option>-fffi</option>
-.</para>
-
- <para>The FFI support in GHC diverges from the Addendum in the following ways:</para>
-
- <itemizedlist>
- <listitem>
- <para>Syntactic forms and library functions proposed in earlier versions
- of the FFI are still supported for backwards compatibility.</para>
- </listitem>
-
- <listitem>
- <para>GHC implements a number of GHC-specific extensions to the FFI
- Addendum. These extensions are described in <xref linkend="sec-ffi-ghcexts" />, but please note that programs using
- these features are not portable. Hence, these features should be
- avoided where possible.</para>
- </listitem>
- </itemizedlist>
-
- <para>The FFI libraries are documented in the accompanying library
- documentation; see for example the <literal>Foreign</literal>
- module.</para>
-
- <sect1 id="sec-ffi-ghcexts">
- <title>GHC extensions to the FFI Addendum</title>
-
- <para>The FFI features that are described in this section are specific to
- GHC. Avoid them where possible to not compromise the portability of the
- resulting code.</para>
-
- <sect2>
- <title>Unboxed types</title>
-
- <para>The following unboxed types may be used as basic foreign types
- (see FFI Addendum, Section 3.2): <literal>Int#</literal>,
- <literal>Word#</literal>, <literal>Char#</literal>,
- <literal>Float#</literal>, <literal>Double#</literal>,
- <literal>Addr#</literal>, <literal>StablePtr# a</literal>,
- <literal>MutableByteArray#</literal>, <literal>ForeignObj#</literal>,
- and <literal>ByteArray#</literal>.</para>
- </sect2>
-
- </sect1>
-
- <sect1 id="sec-ffi-ghc">
- <title>Using the FFI with GHC</title>
-
- <para>The following sections also give some hints and tips on the
- use of the foreign function interface in GHC.</para>
-
- <sect2 id="foreign-export-ghc">
- <title>Using <literal>foreign export</literal> and <literal>foreign import ccall "wrapper"</literal> with GHC</title>
-
- <indexterm><primary><literal>foreign export
- </literal></primary><secondary>with GHC</secondary>
- </indexterm>
-
- <para>When GHC compiles a module (say <filename>M.hs</filename>)
- which uses <literal>foreign export</literal> or
- <literal>foreign import "wrapper"</literal>, it generates two
- additional files, <filename>M_stub.c</filename> and
- <filename>M_stub.h</filename>. GHC will automatically compile
- <filename>M_stub.c</filename> to generate
- <filename>M_stub.o</filename> at the same time.</para>
-
- <para>For a plain <literal>foreign export</literal>, the file
- <filename>M_stub.h</filename> contains a C prototype for the
- foreign exported function, and <filename>M_stub.c</filename>
- contains its definition. For example, if we compile the
- following module:</para>
-
-<programlisting>
-module Foo where
-
-foreign export ccall foo :: Int -> IO Int
-
-foo :: Int -> IO Int
-foo n = return (length (f n))
-
-f :: Int -> [Int]
-f 0 = []
-f n = n:(f (n-1))</programlisting>
-
- <para>Then <filename>Foo_stub.h</filename> will contain
- something like this:</para>
-
-<programlisting>
-#include "HsFFI.h"
-extern HsInt foo(HsInt a0);</programlisting>
-
- <para>and <filename>Foo_stub.c</filename> contains the
- compiler-generated definition of <literal>foo()</literal>. To
- invoke <literal>foo()</literal> from C, just <literal>#include
- "Foo_stub.h"</literal> and call <literal>foo()</literal>.</para>
-
- <para>The <filename>foo_stub.c</filename> and
- <filename>foo_stub.h</filename> files can be redirected using the
- <option>-stubdir</option> option; see <xref linkend="options-output"
- />.</para>
-
- <sect3 id="using-own-main">
- <title>Using your own <literal>main()</literal></title>
-
- <para>Normally, GHC's runtime system provides a
- <literal>main()</literal>, which arranges to invoke
- <literal>Main.main</literal> in the Haskell program. However,
- you might want to link some Haskell code into a program which
- has a main function written in another language, say C. In
- order to do this, you have to initialize the Haskell runtime
- system explicitly.</para>
-
- <para>Let's take the example from above, and invoke it from a
- standalone C program. Here's the C code:</para>
-
-<programlisting>
-#include <stdio.h>
-#include "HsFFI.h"
-
-#ifdef __GLASGOW_HASKELL__
-#include "foo_stub.h"
-#endif
-
-#ifdef __GLASGOW_HASKELL__
-extern void __stginit_Foo ( void );
-#endif
-
-int main(int argc, char *argv[])
-{
- int i;
-
- hs_init(&argc, &argv);
-#ifdef __GLASGOW_HASKELL__
- hs_add_root(__stginit_Foo);
-#endif
-
- for (i = 0; i < 5; i++) {
- printf("%d\n", foo(2500));
- }
-
- hs_exit();
- return 0;
-}</programlisting>
-
- <para>We've surrounded the GHC-specific bits with
- <literal>#ifdef __GLASGOW_HASKELL__</literal>; the rest of the
- code should be portable across Haskell implementations that
- support the FFI standard.</para>
-
- <para>The call to <literal>hs_init()</literal>
- initializes GHC's runtime system. Do NOT try to invoke any
- Haskell functions before calling
- <literal>hs_init()</literal>: strange things will
- undoubtedly happen.</para>
-
- <para>We pass <literal>argc</literal> and
- <literal>argv</literal> to <literal>hs_init()</literal>
- so that it can separate out any arguments for the RTS
- (i.e. those arguments between
- <literal>+RTS...-RTS</literal>).</para>
-
- <para>Next, we call
- <function>hs_add_root</function><indexterm><primary><function>hs_add_root</function></primary>
- </indexterm>, a GHC-specific interface which is required to
- initialise the Haskell modules in the program. The argument
- to <function>hs_add_root</function> should be the name of the
- initialization function for the "root" module in your program
- - in other words, the module which directly or indirectly
- imports all the other Haskell modules in the program. In a
- standalone Haskell program the root module is normally
- <literal>Main</literal>, but when you are using Haskell code
- from a library it may not be. If your program has multiple
- root modules, then you can call
- <function>hs_add_root</function> multiple times, one for each
- root. The name of the initialization function for module
- <replaceable>M</replaceable> is
- <literal>__stginit_<replaceable>M</replaceable></literal>, and
- it may be declared as an external function symbol as in the
- code above.</para>
-
- <para>After we've finished invoking our Haskell functions, we
- can call <literal>hs_exit()</literal>, which
- terminates the RTS. It runs any outstanding finalizers and
- generates any profiling or stats output that might have been
- requested.</para>
-
- <para>There can be multiple calls to
- <literal>hs_init()</literal>, but each one should be matched
- by one (and only one) call to
- <literal>hs_exit()</literal><footnote><para>The outermost
- <literal>hs_exit()</literal> will actually de-initialise the
- system. NOTE that currently GHC's runtime cannot reliably
- re-initialise after this has happened.</para>
- </footnote>.</para>
-
- <para>NOTE: when linking the final program, it is normally
- easiest to do the link using GHC, although this isn't
- essential. If you do use GHC, then don't forget the flag
- <option>-no-hs-main</option><indexterm><primary><option>-no-hs-main</option></primary>
- </indexterm>, otherwise GHC will try to link
- to the <literal>Main</literal> Haskell module.</para>
- </sect3>
-
- <sect3 id="foreign-export-dynamic-ghc">
- <title>Using <literal>foreign import ccall "wrapper"</literal> with GHC</title>
-
- <indexterm><primary><literal>foreign import
- ccall "wrapper"</literal></primary><secondary>with GHC</secondary>
- </indexterm>
-
- <para>When <literal>foreign import ccall "wrapper"</literal> is used
- in a Haskell module, The C stub file <filename>M_stub.c</filename>
- generated by GHC contains small helper functions used by the code
- generated for the imported wrapper, so it must be linked in to the
- final program. When linking the program, remember to include
- <filename>M_stub.o</filename> in the final link command line, or
- you'll get link errors for the missing function(s) (this isn't
- necessary when building your program with <literal>ghc
- ––make</literal>, as GHC will automatically link in the
- correct bits).</para>
- </sect3>
- </sect2>
-
- <sect2 id="glasgow-foreign-headers">
- <title>Using function headers</title>
-
- <indexterm><primary>C calls, function headers</primary></indexterm>
-
- <para>When generating C (using the <option>-fvia-C</option>
- directive), one can assist the C compiler in detecting type
- errors by using the <option>-#include</option> directive
- (<xref linkend="options-C-compiler"/>) to provide
- <filename>.h</filename> files containing function
- headers.</para>
-
- <para>For example,</para>
-
-<programlisting>
-#include "HsFFI.h"
-
-void initialiseEFS (HsInt size);
-HsInt terminateEFS (void);
-HsForeignObj emptyEFS(void);
-HsForeignObj updateEFS (HsForeignObj a, HsInt i, HsInt x);
-HsInt lookupEFS (HsForeignObj a, HsInt i);
-</programlisting>
-
- <para>The types <literal>HsInt</literal>,
- <literal>HsForeignObj</literal> etc. are described in the H98 FFI
- Addendum.</para>
-
- <para>Note that this approach is only
- <emphasis>essential</emphasis> for returning
- <literal>float</literal>s (or if <literal>sizeof(int) !=
- sizeof(int *)</literal> on your architecture) but is a Good
- Thing for anyone who cares about writing solid code. You're
- crazy not to do it.</para>
-
-<para>
-What if you are importing a module from another package, and
-a cross-module inlining exposes a foreign call that needs a supporting
-<option>-#include</option>? If the imported module is from the same package as
-the module being compiled, you should supply all the <option>-#include</option>
-that you supplied when compiling the imported module. If the imported module comes
-from another package, you won't necessarily know what the appropriate
-<option>-#include</option> options are; but they should be in the package
-configuration, which GHC knows about. So if you are building a package, remember
-to put all those <option>-#include</option> options into the package configuration.
-See the <literal>c_includes</literal> field in <xref linkend="package-management"/>.
-</para>
-
-<para>
-It is also possible, according the FFI specification, to put the
-<option>-#include</option> option in the foreign import
-declaration itself:
-<programlisting>
- foreign import "foo.h f" f :: Int -> IO Int
-</programlisting>
-When compiling this module, GHC will generate a C file that includes
-the specified <option>-#include</option>. However, GHC
-<emphasis>disables</emphasis> cross-module inlining for such foreign
-calls, because it doesn't transport the <option>-#include</option>
-information across module boundaries. (There is no fundamental reason for this;
-it was just tiresome to implement. The wrapper, which unboxes the arguments
-etc, is still inlined across modules.) So if you want the foreign call itself
-to be inlined across modules, use the command-line and package-configuration
-<option>-#include</option> mechanism.
-</para>
-
- <sect3 id="finding-header-files">
- <title>Finding Header files</title>
-
- <para>Header files named by the <option>-#include</option>
- option or in a <literal>foreign import</literal> declaration
- are searched for using the C compiler's usual search path.
- You can add directories to this search path using the
- <option>-I</option> option (see <xref
- linkend="c-pre-processor"/>).</para>
-
- <para>Note: header files are ignored unless compiling via C.
- If you had been compiling your code using the native code
- generator (the default) and suddenly switch to compiling via
- C, then you can get unexpected errors about missing include
- files. Compiling via C is enabled automatically when certain
- options are given (eg. <option>-O</option> and
- <option>-prof</option> both enable
- <option>-fvia-C</option>).</para>
- </sect3>
-
- </sect2>
-
- <sect2>
- <title>Memory Allocation</title>
-
- <para>The FFI libraries provide several ways to allocate memory
- for use with the FFI, and it isn't always clear which way is the
- best. This decision may be affected by how efficient a
- particular kind of allocation is on a given compiler/platform,
- so this section aims to shed some light on how the different
- kinds of allocation perform with GHC.</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>alloca</literal> and friends</term>
- <listitem>
- <para>Useful for short-term allocation when the allocation
- is intended to scope over a given <literal>IO</literal>
- computation. This kind of allocation is commonly used
- when marshalling data to and from FFI functions.</para>
-
- <para>In GHC, <literal>alloca</literal> is implemented
- using <literal>MutableByteArray#</literal>, so allocation
- and deallocation are fast: much faster than C's
- <literal>malloc/free</literal>, but not quite as fast as
- stack allocation in C. Use <literal>alloca</literal>
- whenever you can.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>mallocForeignPtr</literal></term>
- <listitem>
- <para>Useful for longer-term allocation which requires
- garbage collection. If you intend to store the pointer to
- the memory in a foreign data structure, then
- <literal>mallocForeignPtr</literal> is
- <emphasis>not</emphasis> a good choice, however.</para>
-
- <para>In GHC, <literal>mallocForeignPtr</literal> is also
- implemented using <literal>MutableByteArray#</literal>.
- Although the memory is pointed to by a
- <literal>ForeignPtr</literal>, there are no actual
- finalizers involved (unless you add one with
- <literal>addForeignPtrFinalizer</literal>), and the
- deallocation is done using GC, so
- <literal>mallocForeignPtr</literal> is normally very
- cheap.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>malloc/free</literal></term>
- <listitem>
- <para>If all else fails, then you need to resort to
- <literal>Foreign.malloc</literal> and
- <literal>Foreign.free</literal>. These are just wrappers
- around the C functions of the same name, and their
- efficiency will depend ultimately on the implementations
- of these functions in your platform's C library. We
- usually find <literal>malloc</literal> and
- <literal>free</literal> to be significantly slower than
- the other forms of allocation above.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>Foreign.Marshal.Pool</literal></term>
- <listitem>
- <para>Pools are currently implemented using
- <literal>malloc/free</literal>, so while they might be a
- more convenient way to structure your memory allocation
- than using one of the other forms of allocation, they
- won't be any more efficient. We do plan to provide an
- improved-performance implementation of Pools in the
- future, however.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
- </sect1>
-</chapter>
-
-<!-- Emacs stuff:
- ;;; Local Variables: ***
- ;;; mode: xml ***
- ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
- ;;; End: ***
- -->
projects / ghc-hetmet.git / blobdiff