From 931268a2dfea91b4114cba87bc36fc93428ed144 Mon Sep 17 00:00:00 2001 From: "Edward Z. Yang" Date: Mon, 1 Jun 2015 09:33:14 -0700 Subject: Replace tabs with spaces. Signed-off-by: Edward Z. Yang --- docs/users_guide/ffi-chap.xml | 236 +++++++++++++++++++++--------------------- 1 file changed, 118 insertions(+), 118 deletions(-) (limited to 'docs/users_guide/ffi-chap.xml') diff --git a/docs/users_guide/ffi-chap.xml b/docs/users_guide/ffi-chap.xml index ab099b2953..acd6f72f7c 100644 --- a/docs/users_guide/ffi-chap.xml +++ b/docs/users_guide/ffi-chap.xml @@ -48,7 +48,7 @@ Foreign function interface (FFI) newtype MyIO a = MIO (IO a) (A reason for doing so might be to prevent the programmer from - calling arbitrary IO procedures in some part of the program.) + calling arbitrary IO procedures in some part of the program.) The Haskell FFI already specifies that arguments and results of foreign imports and exports will be automatically unwrapped if they are @@ -66,18 +66,18 @@ OK: Primitive imports - - GHC extends the FFI with an additional calling convention - prim, e.g.: + + 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 + 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. - + @@ -301,9 +301,9 @@ extern HsInt foo(HsInt a0); "Foo_stub.h" and call foo(). The foo_stub.c and - foo_stub.h files can be redirected using the - option; see . + foo_stub.h files can be redirected using the + option; see . When linking the program, remember to include M_stub.o in the final link command line, or @@ -313,18 +313,18 @@ extern HsInt foo(HsInt a0); correct bits). - Using your own <literal>main()</literal> + Using your own <literal>main()</literal> - Normally, GHC's runtime system provides a - main(), which arranges to invoke - Main.main in the Haskell program. However, - you might want to link some Haskell code into a program which - has a main function written in another language, say C. In - order to do this, you have to initialize the Haskell runtime - system explicitly. + Normally, GHC's runtime system provides a + main(), which arranges to invoke + Main.main in the Haskell program. However, + you might want to link some Haskell code into a program which + has a main function written in another language, say C. In + order to do this, you have to initialize the Haskell runtime + system explicitly. - Let's take the example from above, and invoke it from a - standalone C program. Here's the C code: + Let's take the example from above, and invoke it from a + standalone C program. Here's the C code: #include <stdio.h> @@ -348,43 +348,43 @@ int main(int argc, char *argv[]) return 0; } - 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. + 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 - hs_init(): bad things will - undoubtedly happen. + The call to hs_init() + initializes GHC's runtime system. Do NOT try to invoke any + Haskell functions before calling + hs_init(): bad things will + undoubtedly happen. - We pass references to argc and - argv to hs_init() - so that it can separate out any arguments for the RTS - (i.e. those arguments between - +RTS...-RTS). + We pass references to argc and + argv to hs_init() + so that it can separate out any arguments for the RTS + (i.e. those arguments between + +RTS...-RTS). After we've finished invoking our Haskell functions, we - can call hs_exit(), which terminates the - RTS. - - 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, + can call hs_exit(), which terminates the + RTS. + + 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, see . - . + . - NOTE: when linking the final program, it is normally - easiest to do the link using GHC, although this isn't - essential. If you do use GHC, then don't forget the flag - - , otherwise GHC will try to link - to the Main Haskell module. + NOTE: when linking the final program, it is normally + easiest to do the link using GHC, although this isn't + essential. If you do use GHC, then don't forget the flag + + , otherwise GHC will try to link + to the Main Haskell module. To use +RTS flags with hs_init(), we have to modify the @@ -554,71 +554,71 @@ void mylib_end(void){ kinds of allocation perform with GHC. - - alloca and friends - - Useful for short-term allocation when the allocation - is intended to scope over a given IO - computation. This kind of allocation is commonly used - when marshalling data to and from FFI functions. - - In GHC, alloca is implemented - using MutableByteArray#, so allocation - and deallocation are fast: much faster than C's - malloc/free, but not quite as fast as - stack allocation in C. Use alloca - whenever you can. - - - - - mallocForeignPtr - - Useful for longer-term allocation which requires - garbage collection. If you intend to store the pointer to - the memory in a foreign data structure, then - mallocForeignPtr is - not a good choice, however. - - In GHC, mallocForeignPtr is also - implemented using MutableByteArray#. - Although the memory is pointed to by a - ForeignPtr, there are no actual - finalizers involved (unless you add one with - addForeignPtrFinalizer), and the - deallocation is done using GC, so - mallocForeignPtr is normally very - cheap. - - - - - malloc/free - - If all else fails, then you need to resort to - Foreign.malloc and - Foreign.free. These are just wrappers - around the C functions of the same name, and their - efficiency will depend ultimately on the implementations - of these functions in your platform's C library. We - usually find malloc and - free to be significantly slower than - the other forms of allocation above. - - - - - Foreign.Marshal.Pool - - Pools are currently implemented using - malloc/free, so while they might be a - more convenient way to structure your memory allocation - than using one of the other forms of allocation, they - won't be any more efficient. We do plan to provide an - improved-performance implementation of Pools in the - future, however. - - + + alloca and friends + + Useful for short-term allocation when the allocation + is intended to scope over a given IO + computation. This kind of allocation is commonly used + when marshalling data to and from FFI functions. + + In GHC, alloca is implemented + using MutableByteArray#, so allocation + and deallocation are fast: much faster than C's + malloc/free, but not quite as fast as + stack allocation in C. Use alloca + whenever you can. + + + + + mallocForeignPtr + + Useful for longer-term allocation which requires + garbage collection. If you intend to store the pointer to + the memory in a foreign data structure, then + mallocForeignPtr is + not a good choice, however. + + In GHC, mallocForeignPtr is also + implemented using MutableByteArray#. + Although the memory is pointed to by a + ForeignPtr, there are no actual + finalizers involved (unless you add one with + addForeignPtrFinalizer), and the + deallocation is done using GC, so + mallocForeignPtr is normally very + cheap. + + + + + malloc/free + + If all else fails, then you need to resort to + Foreign.malloc and + Foreign.free. These are just wrappers + around the C functions of the same name, and their + efficiency will depend ultimately on the implementations + of these functions in your platform's C library. We + usually find malloc and + free to be significantly slower than + the other forms of allocation above. + + + + + Foreign.Marshal.Pool + + Pools are currently implemented using + malloc/free, so while they might be a + more convenient way to structure your memory allocation + than using one of the other forms of allocation, they + won't be any more efficient. We do plan to provide an + improved-performance implementation of Pools in the + future, however. + + -- cgit v1.2.1