Skip to content
Snippets Groups Projects
Commit be931552 authored by Duncan Coutts's avatar Duncan Coutts Committed by Reinier Maas
Browse files

Update user guide for byte arrays outside of the heap

Add a sub-subsection in the chapter on GHC extensions to the FFI, under
the existing Memory Allocation subsection.

Explain that it's permitted to have {Mutable}ByteArray# outside the heap
and the tricky associated constraints. Mention the new primop
placeByteArray#.
parent 2f41a273
No related branches found
No related tags found
No related merge requests found
......@@ -811,6 +811,37 @@ the different kinds of allocation perform with GHC.
allocation than using one of the other forms of allocation. They are
backed by the RTS internal arena instead of ``malloc/free``.
Foreign allocation of native byte arrays
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
GHC allows ``ByteArray#`` and ``MutableByteArray#`` to be allocated
outside of the GHC heap. This enables manually allocated data to be
represented as these native types. It is also possible to attach weak
pointers with finalisers to these byte array types. For example, in
principle it is possible to arrange for a memory mapped file to be
presented as a byte array, including a weak pointer finaliser to unmap
the file after it is no longer referenced. This can be useful because
these native types are used directly or indirectly by many libraries.
It does however require some care and attention.
The in-memory representation of ``ByteArray#`` and ``MutableByteArray#``
are exactly the same whether inside or outside the heap. In particular
they use a few prefix words for the object header and array size field.
Note that the object header size is different for normal and profiling
builds. When allocating in foreign memory, space must be made available
for this in the memory layout immediately before the data payload.
In C code, ``#include "rts.h"`` and use ``sizeOf(StgArrBytes)`` or
``sizeOfW(StgArrBytes)`` to get the size of a byte array heap object
header in bytes or words respectively. This is the space that must be
reserved at the memory location immediately before the intended payload.
Then use the primop ``placeByteArray#`` to place the heap object header
at the intended location with the appropriate payload size in bytes.
To add a finaliser, use GHC's weak pointer support. If appropriate make
use of the ability to use C functions for finalisers.
.. _ffi-threads:
Multi-threading and the FFI
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment