<!-- FFI docs as a chapter -->
<Chapter id="ffi">
-<Title>Foreign function interface</Title>
+<Title>Foreign function interface (FFI)</Title>
- <para>The foreign interface consists of the following components:</para>
+ <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 >.
+ The FFI support in GHC diverges from the Addendum in the following ways:
+ </para>
<itemizedlist>
<listitem>
- <para>The Foreign Function Interface language specification
- (which constitutes most of this Chapter, beginning with <xref
- linkend="sec-ffi-intro">). You must use the
- <option>-fglasgow-exts</option> command-line option to make GHC
- understand the <literal>foreign</literal> declarations defined
- by the FFI.</para>
+ <para>Syntactic forms and library functions proposed in earlier versions
+ of the FFI are still supported for backwards compatibility.</para>
</listitem>
<listitem>
- <para>The <literal>Foreign</literal> module (see <xref
- linkend="sec-Foreign">) collects together several interfaces
- which are useful in specifying foreign language interfaces,
- including the following:</para>
-
- <itemizedlist>
- <listitem>
- <para>The <literal>ForeignObj</literal> module (see <xref
- linkend="sec-ForeignObj">), for managing pointers from
- Haskell into the outside world.</para>
- </listitem>
-
- <listitem>
- <para>The <literal>StablePtr</literal> module (see <xref
- linkend="sec-stable-pointers">), for managing pointers into
- Haskell from the outside world.</para>
- </listitem>
-
- <listitem>
- <para>The <literal>CTypes</literal> module (see <xref
- linkend="sec-CTypes">) gives Haskell equivalents for the
- standard C datatypes, for use in making Haskell bindings to
- existing C libraries.</para>
- </listitem>
-
- <listitem>
- <para>The <literal>CTypesISO</literal> module (see <xref
- linkend="sec-CTypesISO">) gives Haskell equivalents for C
- types defined by the ISO C standard.</para>
- </listitem>
-
- <listitem>
- <para>The <literal>Storable</literal> library, for primitive
- marshalling of data types between Haskell and the foreign
- language.</para>
- </listitem>
- </itemizedlist>
-
+ <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>
-&ffi-body;
+ <para>The FFI libraries are documented in the accompanying library
+ documentation; see for example the <literal>Foreign</literal>
+ module.</para>
- <sect1 id="ffi-ghc">
+ <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> with GHC</title>
+ <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>
<para>When GHC compiles a module (say <filename>M.hs</filename>)
which uses <literal>foreign export</literal> or <literal>foreign
- export dynamic</literal>, it generates two
+ 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
<programlisting>
module Foo where
-foreign export foo :: Int -> IO Int
+foreign export ccall foo :: Int -> IO Int
foo :: Int -> IO Int
foo n = return (length (f n))
invoke <literal>foo()</literal> from C, just <literal>#include
"Foo_stub.h"</literal> and call <literal>foo()</literal>.</para>
- <sect3>
+ <sect3 id="using-own-main">
<title>Using your own <literal>main()</literal></title>
<para>Normally, GHC's runtime system provides a
<programlisting>
#include <stdio.h>
-#include "foo_stub.h"
+#include "HsFFI.h"
-#include "RtsAPI.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;
- startupHaskell(argc, argv, __stginit_Foo);
+ hs_init(&argc, &argv);
+#ifdef __GLASGOW_HASKELL__
+ hs_add_root(__stginit_Foo);
+#endif
for (i = 0; i < 5; i++) {
printf("%d\n", foo(2500));
}
- shutdownHaskell();
-
+ hs_exit();
return 0;
}</programlisting>
- <para>The call to <literal>startupHaskell()</literal>
+ <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>startupHaskell()</literal>: strange things will
+ <literal>hs_init()</literal>: strange things will
undoubtedly happen.</para>
<para>We pass <literal>argc</literal> and
- <literal>argv</literal> to <literal>startupHaskell()</literal>
+ <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>The third argument to <literal>startupHaskell()</literal>
- is used for initializing the Haskell modules in the program.
- It must be the name of the initialization function for the
- "top" module in the program/library - in other words, the
- module which directly or indirectly imports all the other
- Haskell modules in the program. In a standalone Haskell
- program this would be module <literal>Main</literal>, but when
- you are only using the Haskell code as a library it may not
- be. If your library doesn't have such a module, then it is
- straightforward to create one, purely for this initialization
- process. The name of the initialization function for module
+ <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>shutdownHaskell()</literal>, which
+ 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>The functions <literal>startupHaskell()</literal> and
- <literal>shutdownHaskell()</literal> may be called only once
- each, and only in that order.</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 export dynamic</literal> with
+ <title>Using <literal>foreign import ccall "wrapper"</literal> with
GHC</title>
- <indexterm><primary><literal>foreign export
- dynamic</literal></primary><secondary>with GHC</secondary>
+ <indexterm><primary><literal>foreign import
+ ccall "wrapper"</literal></primary><secondary>with GHC</secondary>
</indexterm>
- <para>When <literal>foreign export dynamic</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
- <literal>foreign export dynamic</literal>, 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>
+ <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>
<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
</programlisting>
<para>The types <literal>HsInt</literal>,
- <literal>HsForeignObj</literal> etc. are described in <xref
- linkend="sec-ffi-mapping-table">.</para>
+ <literal>HsForeignObj</literal> etc. are described in the H98 FFI
+ Addendum.</para>
<para>Note that this approach is only
<emphasis>essential</emphasis> for returning
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 inlinding 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>
+
+ </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>
+ compuatation. 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 funcitons 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.Marhsal.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 implementaiton of Pools in the
+ future, however.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</sect2>
</sect1>
</Chapter>
projects / ghc-hetmet.git / blobdiff