Table of Contents
GHC (mostly) conforms to the Haskell Foreign Function Interface,
whose definition is part of the Haskell Report on http://www.haskell.org/
.
FFI support is enabled by default, but can be enabled or disabled explicitly with the -XForeignFunctionInterface
flag.
GHC implements a number of GHC-specific extensions to the FFI Addendum. These extensions are described in Section 8.1, “GHC extensions to the FFI Addendum”, but please note that programs using these features are not portable. Hence, these features should be avoided where possible.
The FFI libraries are documented in the accompanying library
documentation; see for example the
Foreign
module.
The FFI features that are described in this section are specific to GHC. Your code will not be portable to other compilers if you use them.
The following unboxed types may be used as basic foreign types
(see FFI Addendum, Section 3.2): Int#
,
Word#
, Char#
,
Float#
, Double#
,
Addr#
, StablePtr# a
,
MutableByteArray#
, ForeignObj#
,
and ByteArray#
.
The FFI spec requires the IO monad to appear in various places,
but it can sometimes be convenient to wrap the IO monad in a
newtype
, thus:
newtype MyIO a = MIO (IO a)
(A reason for doing so might be to prevent the programmer from calling arbitrary IO procedures in some part of the program.)
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 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 OK:
foreign import foo :: Int -> MyIO Int foreign import "dynamic" baz :: (Int -> MyIO Int) -> CInt -> MyIO Int
GHC extends the FFI with an additional calling convention
prim
, e.g.:
foreign import prim "foo" foo :: ByteArray# -> (# Int#, Int# #)
This is used to import functions written in Cmm code that follow an internal GHC calling convention. This feature is not intended for use outside of the core libraries that come with GHC. For more details see the GHC developer wiki.
This concerns the interaction of foreign calls
with Control.Concurrent.throwTo
.
Normally when the target of a throwTo
is
involved in a foreign call, the exception is not raised
until the call returns, and in the meantime the caller is
blocked. This can result in unresponsiveness, which is
particularly undesirable in the case of user interrupt
(e.g. Control-C). The default behaviour when a Control-C
signal is received (SIGINT
on Unix) is to raise
the UserInterrupt
exception in the main
thread; if the main thread is blocked in a foreign call at
the time, then the program will not respond to the user
interrupt.
The problem is that it is not possible in general to
interrupt a foreign call safely. However, GHC does provide
a way to interrupt blocking system calls which works for
most system calls on both Unix and Windows. When the
InterruptibleFFI
extension is enabled,
a foreign call
can be annotated with interruptible
instead
of safe
or unsafe
:
foreign import ccall interruptible "sleep" :: CUint -> IO CUint
interruptible
behaves exactly as
safe
, except that when
a throwTo
is directed at a thread in an
interruptible foreign call, an OS-specific mechanism will be
used to attempt to cause the foreign call to return:
The thread making the foreign call is sent
a SIGPIPE
signal
using pthread_kill()
. This is
usually enough to cause a blocking system call to
return with EINTR
(GHC by default
installs an empty signal handler
for SIGPIPE
, to override the
default behaviour which is to terminate the process
immediately).
[Vista and later only] The RTS calls the Win32
function CancelSynchronousIO
,
which will cause a blocking I/O operation to return
with the
error ERROR_OPERATION_ABORTED
.
If the system call is successfully interrupted, it will
return to Haskell whereupon the exception can be raised. Be
especially careful when
using interruptible
that the caller of
the foreign function is prepared to deal with the
consequences of the call being interrupted; on Unix it is
good practice to check for EINTR
always,
but on Windows it is not typically necessary to
handle ERROR_OPERATION_ABORTED
.
The CApiFFI
extension allows a calling
convention of capi
to be used in foreign
declarations, e.g.
foreign import capi "header.h f" f :: CInt -> IO CInt
Rather than generating code to call f
according to the platform's ABI, we instead call
f
using the C API defined in the header
header.h
. Thus f
can be
called even if it may be defined as a CPP
#define
rather than a proper function.
When using capi
, it is also possible to
import values, rather than functions. For example,
foreign import capi "pi.h value pi" c_pi :: CDouble
will work regardless of whether pi
is
defined as
const double pi = 3.14;
or with
#define pi 3.14
In order to tell GHC the C type that a Haskell type
corresponds to when it is used with the CAPI, a
CTYPE
pragma can be used on the type
definition. The header which defines the type can optionally
also be specified. The syntax looks like:
data {-# CTYPE "unistd.h" "useconds_t" #-} T = ... newtype {-# CTYPE "useconds_t" #-} T = ...
void hs_thread_done(void);
GHC allocates a small amount of thread-local memory when a
thread calls a Haskell function via a foreign
export
. This memory is not normally freed until
hs_exit()
; the memory is cached so that
subsequent calls into Haskell are fast. However, if your
application is long-running and repeatedly creates new
threads that call into Haskell, you probably want to arrange
that this memory is freed in those threads that have
finished calling Haskell functions. To do this, call
hs_thread_done()
from the thread whose
memory you want to free.
Calling hs_thread_done()
is entirely
optional. You can call it as often or as little as you
like. It is safe to call it from a thread that has never
called any Haskell functions, or one that never will. If
you forget to call it, the worst that can happen is that
some memory remains allocated until
hs_exit()
is called. If you call it too
often, the worst that can happen is that the next call to a
Haskell function incurs some extra overhead.