diff options
author | Edward Z. Yang <ezyang@cs.stanford.edu> | 2015-06-01 09:33:14 -0700 |
---|---|---|
committer | Edward Z. Yang <ezyang@cs.stanford.edu> | 2015-06-01 09:33:14 -0700 |
commit | 931268a2dfea91b4114cba87bc36fc93428ed144 (patch) | |
tree | e54a51b2b8b736ffa8a78966c9743fe6fbc7502f /docs | |
parent | 403cfc9187b9df560768bb809f4d280fb999639c (diff) | |
download | haskell-931268a2dfea91b4114cba87bc36fc93428ed144.tar.gz |
Replace tabs with spaces.
Signed-off-by: Edward Z. Yang <ezyang@cs.stanford.edu>
Diffstat (limited to 'docs')
-rw-r--r-- | docs/users_guide/ffi-chap.xml | 236 |
1 files changed, 118 insertions, 118 deletions
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) </programlisting> (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.) </para> <para>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: <sect2 id="ffi-prim"> <title>Primitive imports</title> - <para> - GHC extends the FFI with an additional calling convention - <literal>prim</literal>, e.g.: + <para> + GHC extends the FFI with an additional calling convention + <literal>prim</literal>, e.g.: <programlisting> foreign import prim "foo" foo :: ByteArray# -> (# Int#, Int# #) </programlisting> - 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 <ulink linkend="http://ghc.haskell.org/trac/ghc/wiki/Commentary/PrimOps"> + 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 <ulink linkend="http://ghc.haskell.org/trac/ghc/wiki/Commentary/PrimOps"> GHC developer wiki</ulink>. - </para> + </para> </sect2> <sect2 id="ffi-interruptible"> @@ -301,9 +301,9 @@ extern HsInt foo(HsInt a0);</programlisting> "Foo_stub.h"</literal> and call <literal>foo()</literal>.</para> <para>The <filename>foo_stub.c</filename> and - <filename>foo_stub.h</filename> files can be redirected using the - <option>-stubdir</option> option; see <xref linkend="options-output" - />.</para> + <filename>foo_stub.h</filename> files can be redirected using the + <option>-stubdir</option> option; see <xref linkend="options-output" + />.</para> <para>When linking the program, remember to include <filename>M_stub.o</filename> in the final link command line, or @@ -313,18 +313,18 @@ extern HsInt foo(HsInt a0);</programlisting> correct bits).</para> <sect3 id="using-own-main"> - <title>Using your own <literal>main()</literal></title> + <title>Using your own <literal>main()</literal></title> - <para>Normally, GHC's runtime system provides a - <literal>main()</literal>, which arranges to invoke - <literal>Main.main</literal> 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.</para> + <para>Normally, GHC's runtime system provides a + <literal>main()</literal>, which arranges to invoke + <literal>Main.main</literal> 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.</para> - <para>Let's take the example from above, and invoke it from a - standalone C program. Here's the C code:</para> + <para>Let's take the example from above, and invoke it from a + standalone C program. Here's the C code:</para> <programlisting> #include <stdio.h> @@ -348,43 +348,43 @@ int main(int argc, char *argv[]) return 0; }</programlisting> - <para>We've surrounded the GHC-specific bits with - <literal>#ifdef __GLASGOW_HASKELL__</literal>; the rest of the - code should be portable across Haskell implementations that - support the FFI standard.</para> + <para>We've surrounded the GHC-specific bits with + <literal>#ifdef __GLASGOW_HASKELL__</literal>; the rest of the + code should be portable across Haskell implementations that + support the FFI standard.</para> - <para>The call to <literal>hs_init()</literal> - initializes GHC's runtime system. Do NOT try to invoke any - Haskell functions before calling - <literal>hs_init()</literal>: bad things will - undoubtedly happen.</para> + <para>The call to <literal>hs_init()</literal> + initializes GHC's runtime system. Do NOT try to invoke any + Haskell functions before calling + <literal>hs_init()</literal>: bad things will + undoubtedly happen.</para> - <para>We pass references to <literal>argc</literal> and - <literal>argv</literal> to <literal>hs_init()</literal> - so that it can separate out any arguments for the RTS - (i.e. those arguments between - <literal>+RTS...-RTS</literal>).</para> + <para>We pass references to <literal>argc</literal> and + <literal>argv</literal> to <literal>hs_init()</literal> + so that it can separate out any arguments for the RTS + (i.e. those arguments between + <literal>+RTS...-RTS</literal>).</para> <para>After we've finished invoking our Haskell functions, we - can call <literal>hs_exit()</literal>, which terminates the - RTS.</para> - - <para>There can be multiple calls to - <literal>hs_init()</literal>, but each one should be matched - by one (and only one) call to - <literal>hs_exit()</literal><footnote><para>The outermost - <literal>hs_exit()</literal> will actually de-initialise the - system. NOTE that currently GHC's runtime cannot reliably - re-initialise after this has happened, + can call <literal>hs_exit()</literal>, which terminates the + RTS.</para> + + <para>There can be multiple calls to + <literal>hs_init()</literal>, but each one should be matched + by one (and only one) call to + <literal>hs_exit()</literal><footnote><para>The outermost + <literal>hs_exit()</literal> will actually de-initialise the + system. NOTE that currently GHC's runtime cannot reliably + re-initialise after this has happened, see <xref linkend="infelicities-ffi" />.</para> - </footnote>.</para> + </footnote>.</para> - <para>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 - <option>-no-hs-main</option><indexterm><primary><option>-no-hs-main</option></primary> - </indexterm>, otherwise GHC will try to link - to the <literal>Main</literal> Haskell module.</para> + <para>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 + <option>-no-hs-main</option><indexterm><primary><option>-no-hs-main</option></primary> + </indexterm>, otherwise GHC will try to link + to the <literal>Main</literal> Haskell module.</para> <para>To use <literal>+RTS</literal> flags with <literal>hs_init()</literal>, we have to modify the @@ -554,71 +554,71 @@ void mylib_end(void){ kinds of allocation perform with GHC.</para> <variablelist> - <varlistentry> - <term><literal>alloca</literal> and friends</term> - <listitem> - <para>Useful for short-term allocation when the allocation - is intended to scope over a given <literal>IO</literal> - computation. This kind of allocation is commonly used - when marshalling data to and from FFI functions.</para> - - <para>In GHC, <literal>alloca</literal> is implemented - using <literal>MutableByteArray#</literal>, so allocation - and deallocation are fast: much faster than C's - <literal>malloc/free</literal>, but not quite as fast as - stack allocation in C. Use <literal>alloca</literal> - whenever you can.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>mallocForeignPtr</literal></term> - <listitem> - <para>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 - <literal>mallocForeignPtr</literal> is - <emphasis>not</emphasis> a good choice, however.</para> - - <para>In GHC, <literal>mallocForeignPtr</literal> is also - implemented using <literal>MutableByteArray#</literal>. - Although the memory is pointed to by a - <literal>ForeignPtr</literal>, there are no actual - finalizers involved (unless you add one with - <literal>addForeignPtrFinalizer</literal>), and the - deallocation is done using GC, so - <literal>mallocForeignPtr</literal> is normally very - cheap.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>malloc/free</literal></term> - <listitem> - <para>If all else fails, then you need to resort to - <literal>Foreign.malloc</literal> and - <literal>Foreign.free</literal>. 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 <literal>malloc</literal> and - <literal>free</literal> to be significantly slower than - the other forms of allocation above.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>Foreign.Marshal.Pool</literal></term> - <listitem> - <para>Pools are currently implemented using - <literal>malloc/free</literal>, 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.</para> - </listitem> - </varlistentry> + <varlistentry> + <term><literal>alloca</literal> and friends</term> + <listitem> + <para>Useful for short-term allocation when the allocation + is intended to scope over a given <literal>IO</literal> + computation. This kind of allocation is commonly used + when marshalling data to and from FFI functions.</para> + + <para>In GHC, <literal>alloca</literal> is implemented + using <literal>MutableByteArray#</literal>, so allocation + and deallocation are fast: much faster than C's + <literal>malloc/free</literal>, but not quite as fast as + stack allocation in C. Use <literal>alloca</literal> + whenever you can.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>mallocForeignPtr</literal></term> + <listitem> + <para>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 + <literal>mallocForeignPtr</literal> is + <emphasis>not</emphasis> a good choice, however.</para> + + <para>In GHC, <literal>mallocForeignPtr</literal> is also + implemented using <literal>MutableByteArray#</literal>. + Although the memory is pointed to by a + <literal>ForeignPtr</literal>, there are no actual + finalizers involved (unless you add one with + <literal>addForeignPtrFinalizer</literal>), and the + deallocation is done using GC, so + <literal>mallocForeignPtr</literal> is normally very + cheap.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>malloc/free</literal></term> + <listitem> + <para>If all else fails, then you need to resort to + <literal>Foreign.malloc</literal> and + <literal>Foreign.free</literal>. 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 <literal>malloc</literal> and + <literal>free</literal> to be significantly slower than + the other forms of allocation above.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>Foreign.Marshal.Pool</literal></term> + <listitem> + <para>Pools are currently implemented using + <literal>malloc/free</literal>, 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.</para> + </listitem> + </varlistentry> </variablelist> </sect2> |