wiki:ForeignFunctionInterface

Version 10 (modified by chak@…, 8 years ago) (diff)

--

Foreign Function Interface

See ExtensionDescriptionHowto for information on how to write these extension descriptions. Please add any new extensions to the list of HaskellExtensions.

Brief Explanation

Adds support for invoking code written in other programming languages from Haskell and vice versa. The FFI is designed as a non-intrusive extension to the Haskell 98 standard.

References

Tickets

#35
ForeignFunctionInterface

Pros

  • Widely accepted and used addendum.
  • Provides an essential facility.

Cons

  • Inaccurate foreign imports can invalidate all guarantees given by Haskell.

Topics that need discussion for the integration into Haskell'

Transparent marshalling of newtypes

  1. The *only* reference is in the sentence in 3.2: The argument types ati produced by fatype must be marshallable foreign types; that is, each ati is either (1) a basic foreign type or (2) a type synonym or renamed datatype of a marshallable foreign type. This is very quiet! The "renamed datatype" nomenclature is never used in practice (only in the Haskell report), and in any case the sentence is hard to unpick without an example or two.
  2. Consider foreign import "dynamic" foo :: (Int -> IO Int) -> .... Sect 3.2 should make it clear whether (Int -> IO Int) is considered a "marshallable foreign type".
  3. I also found the separation of 4.1.3 from 3.2 quite hard to understand. I was searching in 3.2 for "wrapper" and "dynamic" in vain! I don't have a good solution to this, except perhaps some explicit fwd refs, and a clear explanation of the logic behind the structure of the document.
  4. It is legal to use a newtype as an argument type (Section 3.2, the FFI spec uses the term "renamed datatype" to mean newtype here). It doesn't say whether the newtype has to be in scope non-abstractly or not - indeed the intention seems to be that if the newtype is in scope, abstractly or not, it is legal to use it as an argument type. This is what GHC implements.

However, arguably this is wrong. By naming an abstract newtype in a foreign declaration, we can learn something about its implementation: namely whether it is a legal FFI argument type or not. Some abstraction has been lost.

Should we require that newtypes used as foreign argument types be non-abstract? This is undesirable - we often don't want to make the actual representation visible, but we nevertheless want the newtype to be a legal foreign argument type (c.f. the CTypes module, which exports a bunch of newtypes abstractly).

I can't see a simple solution. Perhaps we just declare that when a newtype is exported abstractly, it's suitability as a foreign argument type is still visible.

unsafePerformIO

Some have expressed the opinion that the inclusion of unsafePerformIO sends the wrong signal. They aregue that although it is true that by giving inaccurate foreign imports one can define unsafePerformIO, but that doesn't mean it should be standard. Moreover, as the stated purpose of unsafePerformIO in the FFI (hiding marshalling and unmarshalling for otherwise pure functions) can be achieved with a runST-like device if the language has Rank2Types or RankNTypes.

Personally, I don't see the issue. We are including arbitrary C code. For this to be safe, there are additional proof obligations. The function unsafePerformIO is the same - for it to be safe, additional proof obligations have to be met. Concerning a runST-like device, if the idea is to limit the scope of effects that are permitted by putting it into another monad and using a different interface, then this will at least complicate the API quite considerably. Currently, marshalling is performed by functions that read and write arbitrary memory locations. The FFI needs these functions anyway; hence, any other marshalling would need to add functions in addition to the existing ones. Secondly, marshalling is somewhat unpredictable in that different C libraries require different marshalling. Providing an interface with limited effects that captures all possible situations seems tricky, but if anybody has a concrete proposal, let's see it.

-- ManuelChakravarty?

Include files

Foreign imports may specify a single include file. This is sufficient in theory, but most GHC users prefer to use -#include options instead, and the standard form is poorly supported by GHC. The hierarchical libraries use an INCLUDE pragma as a portable replacement for OPTIONS_GHC -#include. jhc lazily collects the imports needed and only includes the ones needed by the FFI functions used after optimizations. this means you can have FFI calls refering to libraries and includes that are not on a system and still compile the program if none of the routines are used.

The rationale behind the design in the addendum is that for cases where a single include files does not suffice, you can always write your own include file that does something more clever (and include that from Haskell). Include files can be used in so many different ways that any other solution, while covering some more complex uses, will never cover them all, which will force people into the fallback of providing extra include files anyway.

-- ManuelChakravarty?

ccall vs. stdcall

Cross-platform libraries (e.g. HOpenGL) often want to import the same foreign functions using the ccall convention on Unix and the stdcall convention on Windows. The usual method is to use CPP hackery.

Earlier versions of the FFI addendum had another conventions that would automatically adapt. IIRC we remove this eventually, because it wasn't always sufficient. Before considering this again, we should consult the mailing list archives for the exact reason of the earlier removal.

-- ManuelChakravarty?

CString

The specified CString conversions are not yet supported in the hierarchical libraries.

Is this a Haskell' issue?

-- ManuelChakravarty?

Specifying libraries

jhc allows libraries to be specified as well as include files. this is handy for its lazy linking, the syntax is "-lfoo include.h foo_func"

This is another feature that we had for a while and then removed as it didn't always work. I think this is something the package manager should handle.

-- ManuelChakravarty?

Changes to the FFI libraries

Additions:

  • We should also have castCharToCUChar, castCUCharToChar, castCharToCSChar, and castCSCharToChar (i.e., not only for CChar of which it is platform-dependent whether it is signed or not).
  • Types from ISO C99 (with conversion routines):
    WordPtr uintptr_t
    WordMax uintmax_t
    IntPtr  intptr_t
    IntMax  intmax_t
    
    ptrToWordPtr :: Ptr a -> WordPtr
    wordPtrToPtr :: WordPtr -> Ptr a
    
    ptrToIntPtr :: Ptr a -> IntPtr
    intPtrToPtr :: IntPtr -> Ptr a