7.2. Calling foreign functions

7.2.1. Giving the external function a Haskell name

The external function has to be given a Haskell name. The name must be a Haskell varid, so the language rules regarding variable names must be followed, i.e., it must start with a lower case letter followed by a sequence of alphanumeric (`in the Unicode sense') characters or '. [1]

varid : small ( small | large | udigit | ' )*

7.2.2. Naming the external function

The name of the external function consists of two parts, one specifying its location, the other its name:

ext_fun : ext_loc ext_name | ext_name ext_name : string ext_loc : string

For example,

foreign import stdcall "Advapi32" "RegCloseKey" regCloseKey :: Addr -> IO ()

states that the external function named RegCloseKey at location Advapi32 should be bound to the Haskell name regCloseKey. For a Win32 Haskell implementation that supports the loading of DLLs on-the-fly, this declaration will most likely cause the run-time system to load the Advapi32.dll DLL before looking up the function RegCloseKey() therein to get at the function pointer to use when invoking regCloseKey.

Compiled implementations may do something completely different, i.e., mangle "RegCloseKey" to convert it into an archive/import library symbol, that's assumed to be in scope when linking. The details of which are platform (and compiler command-line) dependent.

If the location part is left out, the name of the external function specifies a symbol that is assumed to be in scope when linking.

The location part can either contain an absolute `address' (i.e., path) of the archive/DLL, or just its name, leaving it up to the underlying system (system meaning both RTS/compiler and OS) to resolve the name to its real location.

An implementation is expected to be able to intelligently transform the ext_loc location to fit platform-specific practices for naming dynamic libraries. For instance, given the declaration

foreign import "Foo" "foo" foo :: Int -> Int -> IO ()

an implementation should map Foo to "Foo.dll" on a Win32 platform, and libFoo.so on ELF platforms. If the lookup of the dynamic library with this transformed location name should fail, the implementation should then attempt to use the original name before eventually giving up. As part of their documentation, implementations of foreign import should specify the exact details of how ext_locs are transformed and resolved, including the list of directories searched (and the order in which they are.)

In the case the Haskell name of the imported function is identical to the external name, the ext_fun can be omitted. i.e.,

foreign import sin :: Double -> IO Double

is identical to

foreign import "sin" sin :: Double -> IO Double

7.2.3. Calling conventions

The number of calling conventions supported is fixed:

callconv : ccall | stdcall

ccall

The 'default' calling convention on a platform, i.e., the one used to do (C) function calls.

In the case of x86 platforms, the caller pushes function arguments from right to left on the C stack before calling. The caller is responsible for popping the arguments off of the C stack on return.

stdcall

A Win32 specific calling convention. The same as ccall, except that the callee cleans up the C stack before returning. [2]

Some remarks:

• Interoperating well with external code is the name of the game here, so the guiding principle when deciding on what calling conventions to include in callconv is that there's a demonstrated need for a particular calling convention. Should it emerge that the inclusion of other calling conventions will generally improve the quality of this Haskell FFI, they will be considered for future inclusion in callconv.

• Supporting stdcall (and perhaps other platform-specific calling conventions) raises the issue of whether a Haskell FFI should allow the user to write platform-specific Haskell code. The calling convention is clearly an integral part of an external function's interface, so if the one used differs from the standard one specified by the platform's ABI and that convention is used by a non-trivial amount of external functions, the view of the FFI authors is that a Haskell FFI should support it.

• For foreign import (and other foreign declarations), supplying the calling convention is optional. If it isn't supplied, it is treated as if ccall was specified. Users are encouraged to leave out the specification of the calling convention, if possible.

7.2.4. External function types

The range of types that can be passed as arguments to an external function is restricted (as are the range of results coming back):

prim_type : IO prim_result | prim_result | prim_arg '->' prim_type

• If you associate a non-IO type with an external function, you have the same 'proof obligations' as when you make use of IOExts.unsafePerformIO in your Haskell programs.

• The external function is strict in all its arguments.

• GHC only: The GHC FFI implementation provides one extension to prim_type:

  prim_type : ... | unsafe_arr_ty '->' prim_type unsafe_arr_ty : ByteArray a | MutableByteArray i s a

  GHC permits the passing of its byte array primitive types to external functions. There's some restrictions on when they can be used; see Section Section 7.2.4.1 for more details.

Section Section 7.2.4.2 defines prim_result; Section Section 7.2.4.1 defines prim_arg.

7.2.5. Type mapping

For the FFI to be of any practical use, the properties and sizes of the various types that can be communicated between the Haskell world and the outside, needs to be precisely defined. We do this by presenting a mapping to C, as it is commonly used and most other languages define a mapping to it. Table Table 7-1 defines the mapping between Haskell and C types.

Some remarks:

1. A Haskell system that implements the FFI will supply a header file HsFFI.h that includes target platform specific definitions for the above types and values.

2. The sized numeric types Hs{Int,Word}{8,16,32,64} have a 1-1 mapping to ISO C 99's {,u}int{8,16,32,64}_t. For systems that doesn't support this revision of ISO C, a best-fit mapping onto the supported C types is provided.

3. An implementation which does not support 64 bit integral types on the C side should implement Hs{Int,Word}64 as a struct. In this case the bounds HS_INT64_{MIN,MAX} and HS_WORD64_MAX are undefined.

4. A valid Haskell representation of Int has to be equal to or wider than 30 bits. The HsInt synonym is guaranteed to map onto a C type that satisifies Haskell's requirement for Int.

5. It is guaranteed that Hs{Float,Double} are one of C's floating-point types float/double/long double.

6. It is guaranteed that HsAddr is of the same size as void*, so any other pointer type can be converted to and from HsAddr without any loss of information (K&R, Appendix A6.8).

7. Foreign objects are handled like Addr by the FFI, so there is again the guarantee that HsForeignObj is the same as void*. The separate name is meant as a reminder that there is a finalizer attached to the object pointed to.

8. Stable pointers are passed as addresses by the FFI, but this is only because a void* is used as a generic container in most APIs, not because they are real addresses. To make this special case clear, a separate C type is used here.

9. The bounds are preprocessor macros, so they can be used in #if and for array bounds.

10. Floating-point limits are a little bit more complicated, so preprocessor macros mirroring ISO C's float.h are provided:

    HS_{FLOAT,DOUBLE}_RADIX HS_{FLOAT,DOUBLE}_ROUNDS HS_{FLOAT,DOUBLE}_EPSILON HS_{FLOAT,DOUBLE}_DIG HS_{FLOAT,DOUBLE}_MANT_DIG HS_{FLOAT,DOUBLE}_MIN HS_{FLOAT,DOUBLE}_MIN_EXP HS_{FLOAT,DOUBLE}_MIN_10_EXP HS_{FLOAT,DOUBLE}_MAX HS_{FLOAT,DOUBLE}_MAX_EXP HS_{FLOAT,DOUBLE}_MAX_10_EXP

11. It is guaranteed that Haskell's False/True map to C's 0/1, respectively, and vice versa. The mapping of any other integral value to Bool is left unspecified.

12. To avoid name clashes, identifiers starting with Hs and macros starting with HS_ are reserved for the FFI.

13. GHC only: The GHC specific types ByteArray and MutableByteArray both map to char*.

7.2.6. Some foreign import wrinkles

• By default, a foreign import function is safe. A safe external function may cause a Haskell garbage collection as a result of being called. This will typically happen when the imported function end up calling Haskell functions that reside in the same 'Haskell world' (i.e., shares the same storage manager heap) -- see Section Section 7.4 for details of how the FFI let's you call Haskell functions from the outside. If the programmer can guarantee that the imported function won't call back into Haskell, the foreign import can be marked as 'unsafe' (see Section Section 7.2 for details of how to do this.) Unsafe calls are cheaper than safe ones, so distinguishing the two classes of external calls may be worth your while if you're extra conscious about performance.

• A foreign imported function should clearly not need to know that it is being called from Haskell. One consequence of this is that the lifetimes of the arguments that are passed from Haskell must equal that of a normal C call. For instance, for the following decl,

  foreign import "mumble" mumble :: ForeignObj -> IO () f :: Addr -> IO () f ptr = do fo <- newForeignObj ptr myFinalizer mumble fo

  The ForeignObj must live across the call to mumble even if it is not subsequently used/reachable. Why the insistence on this? Consider what happens if mumble calls a function which calls back into the Haskell world to execute a function, behind our back as it were. This evaluation may possibly cause a garbage collection, with the result that fo may end up being finalised. By guaranteeing that fo will be considered live across the call to mumble, the unfortunate situation where fo is finalised (and hence the reference passed to mumble is suddenly no longer valid) is avoided.