X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=docs%2Fusers_guide%2Fffi-chap.xml;h=b33e95abb6e67ee60164ad14d23f6f5832745eeb;hp=49896b92e0549c6d224425d9986302fe4343f9c5;hb=83d563cb9ede0ba792836e529b1e2929db926355;hpb=836cafeb3edd9c728fe4c86cf90229e1476ad14a diff --git a/docs/users_guide/ffi-chap.xml b/docs/users_guide/ffi-chap.xml index 49896b9..b33e95a 100644 --- a/docs/users_guide/ffi-chap.xml +++ b/docs/users_guide/ffi-chap.xml @@ -9,11 +9,8 @@ Foreign function interface (FFI) GHC (mostly) conforms to the Haskell 98 Foreign Function Interface Addendum 1.0, whose definition is available from http://www.haskell.org/. - To enable FFI support in GHC, give the - flag, or -the - flag which implies -. + To enable FFI support in GHC, give the + flag. GHC implements a number of GHC-specific extensions to the FFI Addendum. These extensions are described in , but please note that programs using @@ -22,7 +19,7 @@ the + Foreign module. GHC extensions to the FFI Addendum @@ -66,6 +63,21 @@ OK: + + + Primitive imports + + GHC extends the FFI with an additional calling convention + prim, e.g.: + + foreign import prim "foo" foo :: ByteArray# -> (# Int#, Int# #) + + This is used to import functions written in Cmm code that follow an + internal GHC calling convention. This feature is not intended for + use outside of the core libraries that come with GHC. For more + details see the GHC developer wiki. + + @@ -254,7 +266,8 @@ int main(int argc, char *argv[]) hs_exit()The outermost hs_exit() will actually de-initialise the system. NOTE that currently GHC's runtime cannot reliably - re-initialise after this has happened. + re-initialise after this has happened, + see . . NOTE: when linking the final program, it is normally @@ -307,133 +320,36 @@ int main(int argc, char *argv[]) hs_exit() to shut down the runtime. - - On the use of <literal>hs_exit()</literal> - - hs_exit() normally causes the termination of - any running Haskell threads in the system, and when - hs_exit() returns, there will be no more Haskell - threads running. The runtime will then shut down the system in an - orderly way, generating profiling - output and statistics if necessary, and freeing all the memory it - owns. - - It isn't always possible to terminate a Haskell thread forcibly: - for example, the thread might be currently executing a foreign call, - and we have no way to force the foreign call to complete. What's - more, the runtime must - assume that in the worst case the Haskell code and runtime are about - to be removed from memory (e.g. if this is a Windows DLL, - hs_exit() is normally called before unloading the - DLL). So hs_exit() must wait - until all outstanding foreign calls return before it can return - itself. - - The upshot of this is that if you have Haskell threads that are - blocked in foreign calls, then hs_exit() may hang - (or possibly busy-wait) until the calls return. Therefore it's a - good idea to make sure you don't have any such threads in the system - when calling hs_exit(). This includes any threads - doing I/O, because I/O may (or may not, depending on the - type of I/O and the platform) be implemented using blocking foreign - calls. - - The GHC runtime treats program exit as a special case, to avoid - the need to wait for blocked threads when a standalone - executable exits. Since the program and all its threads are about to - terminate at the same time that the code is removed from memory, it - isn't necessary to ensure that the threads have exited first. - (Unofficially, if you want to use this fast and loose version of - hs_exit(), then call - shutdownHaskellAndExit() instead). - - Using function headers + Using header files C calls, function headers - When generating C (using the - flag), one can assist the C compiler in detecting type - errors by using the directive - () to provide - .h files containing function - headers. - - For example, - - -#include "HsFFI.h" - -void initialiseEFS (HsInt size); -HsInt terminateEFS (void); -HsForeignObj emptyEFS(void); -HsForeignObj updateEFS (HsForeignObj a, HsInt i, HsInt x); -HsInt lookupEFS (HsForeignObj a, HsInt i); - - - The types HsInt, - HsForeignObj etc. are described in the H98 FFI - Addendum. - - Note that this approach is only - essential for returning - floats (or if sizeof(int) != - sizeof(int *) on your architecture) but is a Good - Thing for anyone who cares about writing solid code. You're - crazy not to do it. - - -What if you are importing a module from another package, and -a cross-module inlining exposes a foreign call that needs a supporting -? If the imported module is from the same package as -the module being compiled, you should supply all the -that you supplied when compiling the imported module. If the imported module comes -from another package, you won't necessarily know what the appropriate - options are; but they should be in the package -configuration, which GHC knows about. So if you are building a package using - Cabal, remember to put all those include files in the package - description (see the includes field in the Cabal - documentation). - - -It is also possible, according the FFI specification, to put the - option in the foreign import -declaration itself: - - foreign import "foo.h f" f :: Int -> IO Int - -When compiling this module, GHC will generate a C file that includes -the specified . However, GHC -disables cross-module inlining for such foreign -calls, because it doesn't transport the -information across module boundaries. (There is no fundamental reason for this; -it was just tiresome to implement. The wrapper, which unboxes the arguments -etc, is still inlined across modules.) So if you want the foreign call itself -to be inlined across modules, use the command-line and package-configuration - mechanism. - - - - Finding Header files - - Header files named by the - option or in a foreign import declaration - are searched for using the C compiler's usual search path. - You can add directories to this search path using the - option (see ). - - Note: header files are ignored unless compiling via C. - If you had been compiling your code using the native code - generator (the default) and suddenly switch to compiling via - C, then you can get unexpected errors about missing include - files. Compiling via C is enabled automatically when certain - options are given (eg. and - both enable - ). - + C functions are normally declared using prototypes in a C + header file. Earlier versions of GHC (6.8.3 and + earlier) #included the header file in + the C source file generated from the Haskell code, and the C + compiler could therefore check that the C function being + called via the FFI was being called at the right type. + + GHC no longer includes external header files when + compiling via C, so this checking is not performed. The + change was made for compatibility with the native code backend + (-fasm) and to comply strictly with the FFI + specification, which requires that FFI calls are not subject + to macro expansion and other CPP conversions that may be + applied when using C header files. This approach also + simplifies the inlining of foreign calls across module and + package boundaries: there's no need for the header file to be + available when compiling an inlined version of a foreign call, + so the compiler is free to inline foreign calls in any + context. + + The -#include option is now + deprecated, and the include-files field + in a Cabal package specification is ignored. @@ -515,12 +431,147 @@ to be inlined across modules, use the command-line and package-configuration + + + Multi-threading and the FFI + + In order to use the FFI in a multi-threaded setting, you must + use the option + (see ). + + + Foreign imports and multi-threading + + When you call a foreign imported + function that is annotated as safe (the + default), and the program was linked + using , then the call will run + concurrently with other running Haskell threads. If the + program was linked without , + then the other Haskell threads will be blocked until the + call returns. + + This means that if you need to make a foreign call to + a function that takes a long time or blocks indefinitely, + then you should mark it safe and + use . Some library functions + make such calls internally; their documentation should + indicate when this is the case. + + If you are making foreign calls from multiple Haskell + threads and using , make sure that + the foreign code you are calling is thread-safe. In + particularly, some GUI libraries are not thread-safe and + require that the caller only invokes GUI methods from a + single thread. If this is the case, you may need to + restrict your GUI operations to a single Haskell thread, + and possibly also use a bound thread (see + ). + + Note that foreign calls made by different Haskell + threads may execute in parallel, even + when the +RTS -N flag is not being used + (). The +RTS + -N flag controls parallel execution of Haskell + threads, but there may be an arbitrary number of foreign + calls in progress at any one time, regardless of + the +RTS -N value. + + If a call is annotated as interruptible + and the program was multithreaded, the call may be + interrupted in the event that the Haskell thread receives an + exception. The mechanism by which the interrupt occurs + is platform dependent, but is intended to cause blocking + system calls to return immediately with an interrupted error + code. The underlying operating system thread is not to be + destroyed. + + + + The relationship between Haskell threads and OS + threads + + Normally there is no fixed relationship between Haskell + threads and OS threads. This means that when you make a + foreign call, that call may take place in an unspecified OS + thread. Furthermore, there is no guarantee that multiple + calls made by one Haskell thread will be made by the same OS + thread. + + This usually isn't a problem, and it allows the GHC + runtime system to make efficient use of OS thread resources. + However, there are cases where it is useful to have more + control over which OS thread is used, for example when + calling foreign code that makes use of thread-local state. + For cases like this, we provide bound + threads, which are Haskell threads tied to a + particular OS thread. For information on bound threads, see + the documentation + for the Control.Concurrent + module. + + + + Foreign exports and multi-threading + + When the program is linked + with , then you may + invoke foreign exported functions from + multiple OS threads concurrently. The runtime system must + be initialised as usual by + calling hs_init() + and hs_add_root, and these calls must + complete before invoking any foreign + exported functions. + + + + On the use of <literal>hs_exit()</literal> + + hs_exit() normally causes the termination of + any running Haskell threads in the system, and when + hs_exit() returns, there will be no more Haskell + threads running. The runtime will then shut down the system in an + orderly way, generating profiling + output and statistics if necessary, and freeing all the memory it + owns. + + It isn't always possible to terminate a Haskell thread forcibly: + for example, the thread might be currently executing a foreign call, + and we have no way to force the foreign call to complete. What's + more, the runtime must + assume that in the worst case the Haskell code and runtime are about + to be removed from memory (e.g. if this is a Windows DLL, + hs_exit() is normally called before unloading the + DLL). So hs_exit() must wait + until all outstanding foreign calls return before it can return + itself. + + The upshot of this is that if you have Haskell threads that are + blocked in foreign calls, then hs_exit() may hang + (or possibly busy-wait) until the calls return. Therefore it's a + good idea to make sure you don't have any such threads in the system + when calling hs_exit(). This includes any threads + doing I/O, because I/O may (or may not, depending on the + type of I/O and the platform) be implemented using blocking foreign + calls. + + The GHC runtime treats program exit as a special case, to avoid + the need to wait for blocked threads when a standalone + executable exits. Since the program and all its threads are about to + terminate at the same time that the code is removed from memory, it + isn't necessary to ensure that the threads have exited first. + (Unofficially, if you want to use this fast and loose version of + hs_exit(), then call + shutdownHaskellAndExit() instead). + + +