X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fffi-chap.sgml;h=a92689f2dcc5b90dfea6be2d736849e8e1a8d74d;hb=94fb7e7288a47f7b411ffd4bfa432f94f96f197e;hp=c61e9679493cb46bb65b102cac074e0b223621e7;hpb=34b568ce754f3bd56dc59d285a9d9e9e79c370e5;p=ghc-hetmet.git
diff --git a/ghc/docs/users_guide/ffi-chap.sgml b/ghc/docs/users_guide/ffi-chap.sgml
index c61e967..a92689f 100644
--- a/ghc/docs/users_guide/ffi-chap.sgml
+++ b/ghc/docs/users_guide/ffi-chap.sgml
@@ -132,64 +132,83 @@ extern HsInt foo(HsInt a0);
#include <stdio.h>
-#include "foo_stub.h"
+#include "HsFFI.h"
-#include "RtsAPI.h"
+#ifdef __GLASGOW_HASKELL__
+#include "foo_stub.h"
+#endif
+#ifdef __GLASGOW_HASKELL__
extern void __stginit_Foo ( void );
+#endif
int main(int argc, char *argv[])
{
int i;
- startupHaskell(argc, argv, __stginit_Foo);
+ hs_init(&argc, &argv);
+#ifdef __GLASGOW_HASKELL__
+ hs_add_root(__stginit_Foo);
+#endif
for (i = 0; i < 5; i++) {
printf("%d\n", foo(2500));
}
- shutdownHaskell();
-
+ hs_exit();
return 0;
}
- The call to startupHaskell()
+ We've surrounded the GHC-specific bits with
+ #ifdef __GLASGOW_HASKELL__; the rest of the
+ code should be portable across Haskell implementations that
+ support the FFI standard.
+
+ The call to hs_init()
initializes GHC's runtime system. Do NOT try to invoke any
Haskell functions before calling
- startupHaskell(): strange things will
+ hs_init(): strange things will
undoubtedly happen.
We pass argc and
- argv to startupHaskell()
+ argv to hs_init()
so that it can separate out any arguments for the RTS
(i.e. those arguments between
+RTS...-RTS).
- The third argument to startupHaskell()
- is used for initializing the Haskell modules in the program.
- It must be the name of the initialization function for the
- "top" module in the program/library - in other words, the
- module which directly or indirectly imports all the other
- Haskell modules in the program. In a standalone Haskell
- program this would be module Main, but when
- you are only using the Haskell code as a library it may not
- be. If your library doesn't have such a module, then it is
- straightforward to create one, purely for this initialization
- process. The name of the initialization function for module
+ Next, we call
+ hs_add_rooths_add_root
+ , a GHC-specific interface which is required to
+ initialise the Haskell modules in the program. The argument
+ to hs_add_root should be the name of the
+ initialization function for the "root" module in your program
+ - in other words, the module which directly or indirectly
+ imports all the other Haskell modules in the program. In a
+ standalone Haskell program the root module is normally
+ Main, but when you are using Haskell code
+ from a library it may not be. If your program has multiple
+ root modules, then you can call
+ hs_add_root multiple times, one for each
+ root. The name of the initialization function for module
M is
__stginit_M, and
it may be declared as an external function symbol as in the
code above.
After we've finished invoking our Haskell functions, we
- can call shutdownHaskell(), which
+ can call hs_exit(), which
terminates the RTS. It runs any outstanding finalizers and
generates any profiling or stats output that might have been
requested.
- The functions startupHaskell() and
- shutdownHaskell() may be called only once
- each, and only in that order.
+ There can be multiple calls to
+ hs_init(), but each one should be matched
+ by one (and only one) call to
+ 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.
+ .
NOTE: when linking the final program, it is normally
easiest to do the link using GHC, although this isn't