</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>
+ Addendum 1.0, whose definition is available from <ulink url="http://www.haskell.org/"><literal>http://www.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
+ </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>GHC implements a number of GHC-specific extensions to the FFI
+ Addendum. These extensions are described in <xref linkend="ffi-ghcexts" />, but please note that programs using
+ these features are not portable. Hence, these features should be
+ avoided where possible.</para>
<para>The FFI libraries are documented in the accompanying library
- documentation; see for example the <literal>Foreign</literal>
- module.</para>
+ documentation; see for example the
+ <ulink url="../libraries/base/Control-Concurrent.html"><literal>Foreign</literal></ulink> module.</para>
- <sect1 id="sec-ffi-ghcexts">
+ <sect1 id="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>
+ GHC. Your code will not be portable to other compilers if you use them.</para>
<sect2>
<title>Unboxed types</title>
</para>
<para>The Haskell FFI already specifies that arguments and results of
foreign imports and exports will be automatically unwrapped if they are
-newtypes (Section 3.2 of the FFI addendum). GHC extends the FFI by automatically unnwrapping any newtypes that
+newtypes (Section 3.2 of the FFI addendum). GHC extends the FFI by automatically unwrapping any newtypes that
wrap the IO monad itself.
More precisely, wherever the FFI specification requires an IO type, GHC will
accept any newtype-wrapping of an IO type. For example, these declarations are
</programlisting>
</para>
</sect2>
-
</sect1>
- <sect1 id="sec-ffi-ghc">
+ <sect1 id="ffi-ghc">
<title>Using the FFI with GHC</title>
<para>The following sections also give some hints and tips on the
<option>-stubdir</option> option; see <xref linkend="options-output"
/>.</para>
+ <para>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 id="using-own-main">
<title>Using your own <literal>main()</literal></title>
<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
+ <literal>hs_init()</literal>: bad things will
undoubtedly happen.</para>
- <para>We pass <literal>argc</literal> and
+ <para>We pass references to <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
<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>
+ code above. Note that the symbol name should be transformed
+ according to the Z-encoding:</para>
+
+ <informaltable>
+ <tgroup cols="2" align="left" colsep="1" rowsep="1">
+ <thead>
+ <row>
+ <entry>Character</entry>
+ <entry>Replacement</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>.</literal></entry>
+ <entry><literal>zd</literal></entry>
+ </row>
+ <row>
+ <entry><literal>_</literal></entry>
+ <entry><literal>zu</literal></entry>
+ </row>
+ <row>
+ <entry><literal>`</literal></entry>
+ <entry><literal>zq</literal></entry>
+ </row>
+ <row>
+ <entry><literal>Z</literal></entry>
+ <entry><literal>ZZ</literal></entry>
+ </row>
+ <row>
+ <entry><literal>z</literal></entry>
+ <entry><literal>zz</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
<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>
+ can call <literal>hs_exit()</literal>, which terminates the
+ RTS.</para>
<para>There can be multiple calls to
<literal>hs_init()</literal>, but each one should be matched
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>
+ <sect3 id="ffi-library">
+ <title>Making a Haskell library that can be called from foreign
+ code</title>
- <indexterm><primary><literal>foreign import
- ccall "wrapper"</literal></primary><secondary>with GHC</secondary>
- </indexterm>
+ <para>The scenario here is much like in <xref linkend="using-own-main"
+ />, except that the aim is not to link a complete program, but to
+ make a library from Haskell code that can be deployed in the same
+ way that you would deploy a library of C code.</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>
+ <para>The main requirement here is that the runtime needs to be
+ initialized before any Haskell code can be called, so your library
+ should provide initialisation and deinitialisation entry points,
+ implemented in C or C++. For example:</para>
+
+<programlisting>
+ HsBool mylib_init(void){
+ int argc = ...
+ char *argv[] = ...
+
+ // Initialize Haskell runtime
+ hs_init(&argc, &argv);
+
+ // Tell Haskell about all root modules
+ hs_add_root(__stginit_Foo);
+
+ // do any other initialization here and
+ // return false if there was a problem
+ return HS_BOOL_TRUE;
+ }
+
+ void mylib_end(void){
+ hs_exit();
+ }
+</programlisting>
+
+ <para>The initialisation routine, <literal>mylib_init</literal>, calls
+ <literal>hs_init()</literal> and <literal>hs_add_root()</literal> as
+ normal to initialise the Haskell runtime, and the corresponding
+ deinitialisation function <literal>mylib_end()</literal> calls
+ <literal>hs_exit()</literal> to shut down the runtime.</para>
+ </sect3>
+
+ <sect3 id="hs-exit">
+ <title>On the use of <literal>hs_exit()</literal></title>
+
+ <para><literal>hs_exit()</literal> normally causes the termination of
+ any running Haskell threads in the system, and when
+ <literal>hs_exit()</literal> returns, there will be no more Haskell
+ threads running. The runtime will then shut down the system in an
+ orderly way, generating profiling
+ output and statistics if necessary, and freeing all the memory it
+ owns.</para>
+
+ <para>It isn't always possible to terminate a Haskell thread forcibly:
+ for example, the thread might be currently executing a foreign call,
+ and we have no way to force the foreign call to complete. What's
+ more, the runtime must
+ assume that in the worst case the Haskell code and runtime are about
+ to be removed from memory (e.g. if this is a <link linkend="win32-dlls">Windows DLL</link>,
+ <literal>hs_exit()</literal> is normally called before unloading the
+ DLL). So <literal>hs_exit()</literal> <emphasis>must</emphasis> wait
+ until all outstanding foreign calls return before it can return
+ itself.</para>
+
+ <para>The upshot of this is that if you have Haskell threads that are
+ blocked in foreign calls, then <literal>hs_exit()</literal> may hang
+ (or possibly busy-wait) until the calls return. Therefore it's a
+ good idea to make sure you don't have any such threads in the system
+ when calling <literal>hs_exit()</literal>. This includes any threads
+ doing I/O, because I/O may (or may not, depending on the
+ type of I/O and the platform) be implemented using blocking foreign
+ calls.</para>
+
+ <para>The GHC runtime treats program exit as a special case, to avoid
+ the need to wait for blocked threads when a standalone
+ executable exits. Since the program and all its threads are about to
+ terminate at the same time that the code is removed from memory, it
+ isn't necessary to ensure that the threads have exited first.
+ (Unofficially, if you want to use this fast and loose version of
+ <literal>hs_exit()</literal>, then call
+ <literal>shutdownHaskellAndExit()</literal> instead).</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
+ flag), 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
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>
+configuration, which GHC knows about. So if you are building a package using
+ Cabal, remember to put all those include files in the package
+ description (see the <literal>includes</literal> field in the Cabal
+ documentation).</para>
<para>
It is also possible, according the FFI specification, to put the
projects / ghc-hetmet.git / blobdiff