X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fffi.sgml;h=fc53a3d4f02682bd8aa1878e5b457533256ddd6e;hb=cf9a6ffcc7b8bae66831fd451a43e7aee4b839bd;hp=35e6d76bda459b5ea466de042b050b7f60d756a8;hpb=1ef14beacf757bcb2e9b87d218d98c9637cc4d62;p=ghc-hetmet.git diff --git a/docs/ffi.sgml b/docs/ffi.sgml index 35e6d76..fc53a3d 100644 --- a/docs/ffi.sgml +++ b/docs/ffi.sgml @@ -3,28 +3,76 @@ -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. +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. -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: + + + + +extensions to the base language Haskell 98 (most notably foreign +import and foreign export declarations), which +are specified in the present document, + + + + + +a low-level marshalling library, which is part of the +Language part of the Haskell Extension +Library (see ), and a + + + + + +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 ). 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 and ). + + + +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. -The FFI 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. +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.