X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fffi-chap.xml;h=f9f52aec85b363eb61ef40e20f3410c3848e1b51;hb=26f164e5759e9eca73deb0531ddec422d36a6924;hp=a016f10901c954219c725dbc182c22e2716213d9;hpb=c52eb69bb2f51fed830db42f22bab74c6ff05565;p=ghc-hetmet.git
diff --git a/docs/users_guide/ffi-chap.xml b/docs/users_guide/ffi-chap.xml
index a016f10..f9f52ae 100644
--- a/docs/users_guide/ffi-chap.xml
+++ b/docs/users_guide/ffi-chap.xml
@@ -63,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.
+
+
@@ -251,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
@@ -304,50 +320,10 @@ int main(int argc, char *argv[])
hs_exit() to shut down the runtime.
-
- On the use of hs_exit()
-
- 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 filesC calls, function headers
@@ -455,6 +431,133 @@ int main(int argc, char *argv[])
+
+
+ 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.
+
+
+
+ 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 hs_exit()
+
+ 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).
+
+
+