X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fffi.sgml;h=32f14a2afae6e7db26e1b974be24ec4ab976e63f;hb=57c3ca2603ef0f2358d8d246bff1dd47ef97e843;hp=35e6d76bda459b5ea466de042b050b7f60d756a8;hpb=1ef14beacf757bcb2e9b87d218d98c9637cc4d62;p=ghc-hetmet.git diff --git a/docs/ffi.sgml b/docs/ffi.sgml index 35e6d76..32f14a2 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. @@ -63,7 +111,7 @@ Giving a Haskell name and type to an external entry point is clearly an unsafe thing to do, as the external name will in most cases be untyped. The onus is on the programmer using foreign import to ensure that the Haskell type given correctly maps on to the -type of the external function. Section +type of the external function. specifies the mapping from Haskell types to external types. @@ -254,7 +302,7 @@ that the callee cleans up the C stack before returning. -The stdcall is a Microsoft Win32 specific wrinkle; it used +The stdcall is a Microsoft Win32 specific wrinkle; it's used throughout the Win32 API, for instance. On platforms where stdcall isn't meaningful, it should be treated as being equal to ccall. @@ -366,7 +414,7 @@ unsafe_arr_ty : ByteArray 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 +they can be used; see for more details. @@ -376,8 +424,8 @@ for more details. -Section defines -prim_result; Section + defines +prim_result; defines prim_arg. @@ -419,7 +467,7 @@ C-like languages, although the numeric types are explicitly sized. The stable pointer StablePtr type looks out of place in this list of C-like types, but it has a well-defined and simple -C mapping, see Section +C mapping, see for details. @@ -898,12 +946,12 @@ 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 for + 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 for details of +'unsafe' (see for details of how to do this.) Unsafe calls are cheaper than safe ones, so distinguishing the two @@ -1170,7 +1218,7 @@ typedef cType[[Res]] (*Varid_FunPtr) where cType[[]] is the Haskell to C type mapping presented -in Section . +in . @@ -1304,7 +1352,7 @@ is the widest possible data pointer. -Updated defnition of varid in Section +Updated defnition of varid in to reflect Haskell98's.