Data.Primitive.ByteArray

Lifted wrapper for ByteArray#.

Since ByteArray# is an unlifted type and not a member of kind Type, things like [ByteArray#] or IO ByteArray# are ill-typed. To work around this inconvenience this module provides a standard lifted wrapper, inhabiting Type. Clients are expected to use ByteArray in higher-level APIs, but wrap and unwrap ByteArray internally as they please and use functions from GHC.Exts.

The memory representation of a ByteArray is:

╭─────────────┬───╮  ╭────────┬──────┬─────────╮
│ Constructor │ * ┼─►│ Header │ Size │ Payload │
╰─────────────┴───╯  ╰────────┴──────┴─────────╯

And its overhead is the following:

• ByteArray constructor: 1 word

• Pointer to ByteArray#: 1 word

• ByteArray# Header: 1 word

• ByteArray# Size: 1 word

Where a word is the unit of heap allocation, measuring 8 bytes on 64-bit systems, and 4 bytes on 32-bit systems.

Lifted wrapper for MutableByteArray#.

Since MutableByteArray# is an unlifted type and not a member of kind Type, things like [MutableByteArray#] or IO MutableByteArray# are ill-typed. To work around this inconvenience this module provides a standard lifted wrapper, inhabiting Type. Clients are expected to use MutableByteArray in higher-level APIs, but wrap and unwrap MutableByteArray internally as they please and use functions from GHC.Exts.

A boxed, unlifted datatype representing a region of raw memory in the garbage-collected heap, which is not scanned for pointers during garbage collection.

It is created by freezing a MutableByteArray# with unsafeFreezeByteArray#. Freezing is essentially a no-op, as MutableByteArray# and ByteArray# share the same heap structure under the hood.

The immutable and mutable variants are commonly used for scenarios requiring high-performance data structures, like Text, Primitive Vector, Unboxed Array, and ShortByteString.

Another application of fundamental importance is Integer, which is backed by ByteArray#.

The representation on the heap of a Byte Array is:

+------------+-----------------+-----------------------+
|            |                 |                       |
|   HEADER   | SIZE (in bytes) |       PAYLOAD         |
|            |                 |                       |
+------------+-----------------+-----------------------+

To obtain a pointer to actual payload (e.g., for FFI purposes) use byteArrayContents# or mutableByteArrayContents#.

Alternatively, enabling the UnliftedFFITypes extension allows to mention ByteArray# and MutableByteArray# in FFI type signatures directly.

A mutable ByteAray#. It can be created in three ways:

• newByteArray#: Create an unpinned array.

• newPinnedByteArray#: This will create a pinned array,

• newAlignedPinnedByteArray#: This will create a pinned array, with a custom alignment.

Unpinned arrays can be moved around during garbage collection, so you must not store or pass pointers to these values if there is a chance for the garbage collector to kick in. That said, even unpinned arrays can be passed to unsafe FFI calls, because no garbage collection happens during these unsafe calls (see Guaranteed Call Safety in the GHC Manual). For safe FFI calls, byte arrays must be not only pinned, but also kept alive by means of the keepAlive# function for the duration of a call (that's because garbage collection cannot move a pinned array, but is free to scrap it altogether).