X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fffi.sgml;h=0cc2acaaa192999e3f5ce65ff6f189a4cc40f825;hb=13df0a2862ab945e7e404bdacb0bb9c7479accad;hp=e59ff9e42e7c42eb6908c1f3ff3395156edb64b3;hpb=14f3d572dc00dada527b0cb55de03b05a115064a;p=ghc-hetmet.git diff --git a/docs/ffi.sgml b/docs/ffi.sgml index e59ff9e..0cc2aca 100644 --- a/docs/ffi.sgml +++ b/docs/ffi.sgml @@ -1,35 +1,83 @@ - + 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. +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, + + -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. +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. + + + +In the following, we will discuss the language extensions of the FFI (i.e. 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. - + Calling foreign functions @@ -63,12 +111,12 @@ 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 - specifies the mapping from +type of the external function. + specifies the mapping from Haskell types to external types. - + Giving the external function a Haskell name @@ -96,7 +144,7 @@ varid : small ( small | large | udigit | ' )* - + Naming the external function @@ -211,7 +259,7 @@ foreign import "sin" sin :: Double -> IO Double - + Calling conventions @@ -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. @@ -312,7 +360,7 @@ to leave out the specification of the calling convention, if possible. - + External function types @@ -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,12 +424,12 @@ for more details. -Section defines -prim_result; Section + defines +prim_result; defines prim_arg. - + Argument types @@ -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. @@ -535,7 +583,7 @@ be withdrawn sometime in the future.) - + Result type @@ -591,7 +639,7 @@ Haskell newtypes that wrap up ext_ty are also permitte - + Type mapping @@ -601,18 +649,16 @@ 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 - + defines the mapping between Haskell and C types. - +
Mapping of Haskell types to C types - - - + @@ -748,10 +794,6 @@ defines the mapping between Haskell and C types. void* (8) - - - - @@ -889,7 +931,7 @@ macros starting with HS_ are reserved for the FFI. - + Some <Literal>foreign import</Literal> wrinkles @@ -904,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 @@ -932,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 @@ -961,7 +1003,7 @@ valid) is avoided. - + Invoking external functions via a pointer @@ -1014,7 +1056,7 @@ and execute code. - + Exposing Haskell functions @@ -1123,7 +1165,7 @@ outside world. - + Exposing Haskell function values @@ -1176,7 +1218,7 @@ typedef cType[[Res]] (*Varid_FunPtr) where cType[[]] is the Haskell to C type mapping presented -in Section . +in . @@ -1255,7 +1297,7 @@ Foreign.freeHaskellFunctionPtr :: Addr -> IO () - + Code addresses @@ -1286,7 +1328,7 @@ contain the address of the label freeAtLast.