8.2. Using the FFI with GHC

8.2.1. Using foreign export and foreign import ccall "wrapper" with GHC

When GHC compiles a module (say M.hs) which uses foreign export or foreign import "wrapper", it generates two additional files, M_stub.c and M_stub.h. GHC will automatically compile M_stub.c to generate M_stub.o at the same time.

For a plain foreign export, the file M_stub.h contains a C prototype for the foreign exported function, and M_stub.c contains its definition. For example, if we compile the following module:

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))

Then Foo_stub.h will contain something like this:

#include "HsFFI.h"
extern HsInt foo(HsInt a0);

and Foo_stub.c contains the compiler-generated definition of foo(). To invoke foo() from C, just #include "Foo_stub.h" and call foo().

#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;
}

8.2.2. Using function headers

When generating C (using the -fvia-C directive), one can assist the C compiler in detecting type errors by using the -#include directive (Section 4.12.5) to provide .h files containing function headers.

For example,

#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);

The types HsInt, HsForeignObj etc. are described in the H98 FFI Addendum.

Note that this approach is only essential for returning floats (or if sizeof(int) != sizeof(int *) on your architecture) but is a Good Thing for anyone who cares about writing solid code. You're crazy not to do it.

What if you are importing a module from another package, and a cross-module inlining exposes a foreign call that needs a supporting -#include? If the imported module is from the same package as the module being compiled, you should supply all the -#include that you supplied when compiling the imported module. If the imported module comes from another package, you won't necessarily know what the appropriate -#include 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 -#include options into the package configuration. See the c_includes field in Section 4.10.4.

It is also possible, according the FFI specification, to put the -#include option in the foreign import declaration itself:

foreign import "foo.h f" f :: Int -> IO Int

When compiling this module, GHC will generate a C file that includes the specified -#include. However, GHC disables cross-module inlinding for such foreign calls, because it doesn't transport the -#include 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 -#include mechanism.

8.2.3. Memory Allocation

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.