summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorHécate Moonlight <hecate+gitlab@glitchbra.in>2022-04-26 20:34:09 +0200
committerMarge Bot <ben+marge-bot@smart-cactus.org>2022-05-01 22:21:55 -0400
commit60071076d880c9ee189c93e0105a9b3d1ff87a3f (patch)
tree86f875e501f81e9bb14936b929037278a05ea494
parent636f7c62b1c30d130d88d6ad0763d894a8513e8a (diff)
downloadhaskell-60071076d880c9ee189c93e0105a9b3d1ff87a3f.tar.gz
Add documentation to the ByteArray# primetype.
close #21417
-rw-r--r--compiler/GHC/Builtin/primops.txt.pp49
1 files changed, 44 insertions, 5 deletions
diff --git a/compiler/GHC/Builtin/primops.txt.pp b/compiler/GHC/Builtin/primops.txt.pp
index d21d6a1f6f..1e838880a4 100644
--- a/compiler/GHC/Builtin/primops.txt.pp
+++ b/compiler/GHC/Builtin/primops.txt.pp
@@ -1663,22 +1663,61 @@ primop CasSmallArrayOp "casSmallArray#" GenPrimOp
------------------------------------------------------------------------
section "Byte Arrays"
- {Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
+ {A {\tt ByteArray\#} is a region of
raw memory in the garbage-collected heap, which is not
- scanned for pointers. It carries its own size (in bytes).
- There are
- three sets of operations for accessing byte array contents:
+ scanned for pointers.
+ There are three sets of operations for accessing byte array contents:
index for reading from immutable byte arrays, and read/write
for mutable byte arrays. Each set contains operations for a
range of useful primitive data types. Each operation takes
an offset measured in terms of the size of the primitive type
- being read or written.}
+ being read or written.
+
+ }
------------------------------------------------------------------------
primtype ByteArray#
+{
+ 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.
+}
primtype MutableByteArray# s
+{ 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](https://ghc.gitlab.haskell.org/ghc/doc/users_guide/exts/ffi.html#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).
+}
primop NewByteArrayOp_Char "newByteArray#" GenPrimOp
Int# -> State# s -> (# State# s, MutableByteArray# s #)