Chapter 7. Foreign function interface

Table of Contents
7.1. Introduction
7.2. Calling foreign functions
7.3. Invoking external functions via a pointer
7.4. Exposing Haskell functions

7.1. Introduction

The motivation behind this foreign function interface (FFI) specification is to make it possible to describe in Haskell source code the interface to foreign functionality in a Haskell system independent manner. It builds on experiences made with the previous foreign function interfaces provided by GHC and Hugs. However, the FFI specified in this document is not in the market of trying to completely bridge the gap between the actual type of an external function, and what is a convenient type for that function to the Haskell programmer. That is the domain of tools like HaskellDirect or Green Card, both of which are capable of generating Haskell code that uses this FFI.

Generally, the FFI consists of three parts:

  1. extensions to the base language Haskell 98 (most notably foreign import and foreign export declarations), which are specified in the present document,

  2. a low-level marshalling library, which is part of the Language part of the Haskell Extension Library (see Section 4.25 in Haskell Libraries), and a

  3. a high-level marshalling library, which is still under development.

Before diving into the details of the language extension coming with the FFI, let us briefly outline the two other components of the interface.

The low-level marshalling library consists of a portion that is independent of the targeted foreign language and dedicated support for Haskell bindings to C libraries (special support for other languages may be added in the future). The language independent part is given by the module Foreign module (see Section 4.9 in Haskell Libraries). It provides support for handling references to foreign structures, for passing references to Haskell structures out to foreign routines, and for storing primitive data types in raw memory blocks in a portable manner. The support for C libraries essentially provides Haskell representations for all basic types of C (see Section 4.5 in Haskell Libraries and Section 4.6 in Haskell Libraries).

The high-level library, of which the interface definition is not yet finalised, provides routines for marshalling complex Haskell structures as well as handling out and in-out parameters in a convenient, yet protable way.

In the following, we will discuss the language extensions of the FFI (ie, the first point above). They can be split up into two complementary halves; one half that provides Haskell constructs for importing foreign functionality into Haskell, the other which lets you expose Haskell functions to the outside world. We start with the former, how to import external functionality into Haskell.