From 94fb7e7288a47f7b411ffd4bfa432f94f96f197e Mon Sep 17 00:00:00 2001 From: simonmar Date: Tue, 28 Jan 2003 16:57:40 +0000 Subject: [PATCH] [project @ 2003-01-28 16:57:40 by simonmar] Update the FFI docs to use hs_init()/hs_exit() rather than startupHaskell()/shutdownHaskell(). --- ghc/docs/users_guide/ffi-chap.sgml | 65 +++++++++++++++++++++++------------- 1 file changed, 42 insertions(+), 23 deletions(-) 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 -- 1.7.10.4