Commit de26eb1b authored by simonmar's avatar simonmar

[project @ 2003-03-11 10:34:58 by simonmar]

- Remove mention of MutableByteArray and ByteArray

- Add section on memory allocation in the FFI, with emphasis on how
  GHC's implementations of the various kinds of allocation perform.
parent 773da86e
......@@ -41,15 +41,6 @@
GHC. Avoid them where possible to not compromise the portability of the
resulting code.</para>
<sect2>
<title>Arrays</title>
<para>The types <literal>ByteArray</literal> and
<literal>MutableByteArray</literal> may be used as basic foreign types
(see FFI Addendum, Section 3.2). In C land, they map to
<literal>(char *)</literal>.</para>
</sect2>
<sect2>
<title>Unboxed types</title>
......@@ -306,6 +297,85 @@ to be inlined across modules, use the command-line and package-configuration
</para>
</sect2>
<sect2>
<title>Memory Allocation</title>
<para>The FFI libraries provide several ways to allocate memory
for use with the FFI, and it isn't always clear which way is the
best. This decision may be affected by how efficient a
particular kind of allocation is on a given compiler/platform,
so this section aims to shed some light on how the different
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>
compuatation. 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 funcitons 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.Marhsal.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 implementaiton of Pools in the
future, however.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
</Chapter>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment