X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fffi.sgml;h=32f14a2afae6e7db26e1b974be24ec4ab976e63f;hb=b1f21be87465170daff5cf69f513a005f44aac4f;hp=85f8bcf8fdc6293180553ab6879f477ba3804303;hpb=8e5eb3dfef0debc9bf9f914b1a5f5fe3d2717f89;p=ghc-hetmet.git diff --git a/docs/ffi.sgml b/docs/ffi.sgml index 85f8bcf..32f14a2 100644 --- a/docs/ffi.sgml +++ b/docs/ffi.sgml @@ -1,45 +1,78 @@ - + +Introduction + -
+ +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. + - + +Generally, the FFI consists of three parts: + -A Haskell foreign function interface -The GHC Team -
glasgow-haskell-{users,bugs}@dcs.gla.ac.uk -
-version 0.99 -May 2000 + + +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 + + - -Introduction - + + +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 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 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 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 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. @@ -78,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. @@ -269,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. @@ -381,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. @@ -391,8 +424,8 @@ for more details. -Section defines -prim_result; Section + defines +prim_result; defines prim_arg. @@ -434,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. @@ -625,9 +658,7 @@ defines the mapping between Haskell and C types. Mapping of Haskell types to C types - - - + @@ -646,90 +677,80 @@ defines the mapping between Haskell and C types. Char HsChar unspec. integral type - HS_CHAR_MIN -.. - HS_CHAR_MAX + HS_CHAR_MIN .. HS_CHAR_MAX Int HsInt signed integral of unspec. size(4) - HS_INT_MIN -.. - HS_INT_MAX + HS_INT_MIN .. +HS_INT_MAX Int8 (2) HsInt8 8 bit signed integral - HS_INT8_MIN -.. - HS_INT8_MAX + HS_INT8_MIN +.. +HS_INT8_MAX Int16 (2) HsInt16 16 bit signed integral - HS_INT16_MIN -.. - HS_INT16_MAX + HS_INT16_MIN +.. HS_INT16_MAX Int32 (2) HsInt32 32 bit signed integral - HS_INT32_MIN -.. - HS_INT32_MAX + HS_INT32_MIN .. +HS_INT32_MAX Int64 (2,3) HsInt64 64 bit signed integral (3) - HS_INT64_MIN -.. - HS_INT64_MAX + HS_INT64_MIN .. +HS_INT64_MAX Word8 (2) HsWord8 8 bit unsigned integral - 0 -.. - HS_WORD8_MAX + 0 .. +HS_WORD8_MAX Word16 (2) HsWord16 16 bit unsigned integral - 0 -.. - HS_WORD16_MAX + 0 .. +HS_WORD16_MAX Word32 (2) HsWord32 32 bit unsigned integral - 0 -.. - HS_WORD32_MAX + 0 .. +HS_WORD32_MAX Word64 (2,3) HsWord64 64 bit unsigned integral (3) - 0 -.. - HS_WORD64_MAX + 0 .. +HS_WORD64_MAX @@ -737,8 +758,6 @@ defines the mapping between Haskell and C types. HsFloat floating point of unspec. size (5) (10) - - @@ -746,8 +765,6 @@ defines the mapping between Haskell and C types. HsDouble floating point of unspec. size (5) (10) - - @@ -755,8 +772,6 @@ defines the mapping between Haskell and C types. HsBool unspec. integral type (11) - - @@ -764,8 +779,6 @@ defines the mapping between Haskell and C types. HsAddr void* (6) - - @@ -773,8 +786,6 @@ defines the mapping between Haskell and C types. HsForeignObj void* (7) - - @@ -782,12 +793,6 @@ defines the mapping between Haskell and C types. HsStablePtr void* (8) - - - - - - @@ -941,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 @@ -969,7 +974,7 @@ foreign import "mumble" mumble :: ForeignObj -> IO () f :: Addr -> IO () f ptr = do - fo <- makeForeignObj ptr myFinalizer + fo <- newForeignObj ptr myFinalizer mumble fo @@ -1213,7 +1218,7 @@ typedef cType[[Res]] (*Varid_FunPtr) where cType[[]] is the Haskell to C type mapping presented -in Section . +in . @@ -1322,7 +1327,7 @@ contain the address of the label freeAtLast. - +