diff options
author | Andrew Martin <andrew.thaddeus@gmail.com> | 2019-06-06 10:42:35 -0400 |
---|---|---|
committer | Marge Bot <ben+marge-bot@smart-cactus.org> | 2019-06-07 10:20:42 -0400 |
commit | d3915b304f297b8a2534f6abf9c2984837792921 (patch) | |
tree | 684799136075cff6718c2e12f0b9ff2b0de673af | |
parent | 567894b49b9e8f5ced2d0e5f051f2a1d5c9f13e2 (diff) | |
download | haskell-d3915b304f297b8a2534f6abf9c2984837792921.tar.gz |
[skip ci] Improve the documentation of the CNF primops. In this context, the term "size" is ambiguous and is now avoided. Additionally, the distinction between a CNF and the blocks that comprise it has been emphasize. The vocabulary has been made more consistent with the vocabulary in the C source for CNF.
-rw-r--r-- | compiler/prelude/primops.txt.pp | 63 |
1 files changed, 40 insertions, 23 deletions
diff --git a/compiler/prelude/primops.txt.pp b/compiler/prelude/primops.txt.pp index 0053c61152..39e7c4799c 100644 --- a/compiler/prelude/primops.txt.pp +++ b/compiler/prelude/primops.txt.pp @@ -2977,15 +2977,29 @@ primop StableNameToIntOp "stableNameToInt#" GenPrimOp ------------------------------------------------------------------------ section "Compact normal form" + + {Primitives for working with compact regions. The {\tt ghc\-compact} + library and the {\tt compact} library demonstrate how to use these + primitives. The documentation below draws a distinction between + a CNF and a compact block. A CNF contains one or more compact + blocks. The source file {\tt rts\/sm\/CNF.c} + diagrams this relationship. When discussing a compact + block, an additional distinction is drawn between capacity and + utilized bytes. The capacity is the maximum number of bytes that + the compact block can hold. The utilized bytes is the number of + bytes that are actually used by the compact block. + } + ------------------------------------------------------------------------ primtype Compact# primop CompactNewOp "compactNew#" GenPrimOp Word# -> State# RealWorld -> (# State# RealWorld, Compact# #) - { Create a new Compact with the given size (in bytes, not words). - The size is rounded up to a multiple of the allocator block size, - and capped to one mega block. } + { Create a new CNF with a single compact block. The argument is + the capacity of the compact block (in bytes, not words). + The capacity is rounded up to a multiple of the allocator block size + and is capped to one mega block. } with has_side_effects = True out_of_line = True @@ -2993,44 +3007,46 @@ primop CompactNewOp "compactNew#" GenPrimOp primop CompactResizeOp "compactResize#" GenPrimOp Compact# -> Word# -> State# RealWorld -> State# RealWorld - { Set the new allocation size of the compact. This value (in bytes) - determines the size of each block in the compact chain. } + { Set the new allocation size of the CNF. This value (in bytes) + determines the capacity of each compact block in the CNF. It + does not retroactively affect existing compact blocks in the CNF. } with has_side_effects = True out_of_line = True primop CompactContainsOp "compactContains#" GenPrimOp Compact# -> a -> State# RealWorld -> (# State# RealWorld, Int# #) - { Returns 1\# if the object is contained in the compact, 0\# otherwise. } + { Returns 1\# if the object is contained in the CNF, 0\# otherwise. } with out_of_line = True primop CompactContainsAnyOp "compactContainsAny#" GenPrimOp a -> State# RealWorld -> (# State# RealWorld, Int# #) - { Returns 1\# if the object is in any compact at all, 0\# otherwise. } + { Returns 1\# if the object is in any CNF at all, 0\# otherwise. } with out_of_line = True primop CompactGetFirstBlockOp "compactGetFirstBlock#" GenPrimOp Compact# -> State# RealWorld -> (# State# RealWorld, Addr#, Word# #) - { Returns the address and the size (in bytes) of the first block of - a compact. } + { Returns the address and the utilized size (in bytes) of the + first compact block of a CNF.} with out_of_line = True primop CompactGetNextBlockOp "compactGetNextBlock#" GenPrimOp Compact# -> Addr# -> State# RealWorld -> (# State# RealWorld, Addr#, Word# #) - { Given a compact and the address of one its blocks, returns the - next block and its size, or #nullAddr if the argument was the - last block in the compact. } + { Given a CNF and the address of one its compact blocks, returns the + next compact block and its utilized size, or {\tt nullAddr\#} if the + argument was the last compact block in the CNF. } with out_of_line = True primop CompactAllocateBlockOp "compactAllocateBlock#" GenPrimOp Word# -> Addr# -> State# RealWorld -> (# State# RealWorld, Addr# #) - { Attempt to allocate a compact block with the given size (in - bytes, given by the first argument). The {\texttt Addr\#} is a pointer to - previous block of the compact or {\texttt nullAddr\#} to create a new compact. + { Attempt to allocate a compact block with the capacity (in + bytes) given by the first argument. The {\texttt Addr\#} is a pointer + to previous compact block of the CNF or {\texttt nullAddr\#} to create a + new CNF with a single compact block. The resulting block is not known to the GC until {\texttt compactFixupPointers\#} is called on it, and care must be taken @@ -3042,13 +3058,13 @@ primop CompactAllocateBlockOp "compactAllocateBlock#" GenPrimOp primop CompactFixupPointersOp "compactFixupPointers#" GenPrimOp Addr# -> Addr# -> State# RealWorld -> (# State# RealWorld, Compact#, Addr# #) - { Given the pointer to the first block of a compact, and the + { Given the pointer to the first block of a CNF and the address of the root object in the old address space, fix up - the internal pointers inside the compact to account for + the internal pointers inside the CNF to account for a different position in memory than when it was serialized. This method must be called exactly once after importing - a serialized compact, and returns the new compact and - the new adjusted root address. } + a serialized CNF. It returns the new CNF and the new adjusted + root address. } with has_side_effects = True out_of_line = True @@ -3056,10 +3072,10 @@ primop CompactFixupPointersOp "compactFixupPointers#" GenPrimOp primop CompactAdd "compactAdd#" GenPrimOp Compact# -> a -> State# RealWorld -> (# State# RealWorld, a #) { Recursively add a closure and its transitive closure to a - {\texttt Compact\#}, evaluating any unevaluated components at the - same time. Note: {\texttt compactAdd\#} is not thread-safe, so + {\texttt Compact\#} (a CNF), evaluating any unevaluated components + at the same time. Note: {\texttt compactAdd\#} is not thread-safe, so only one thread may call {\texttt compactAdd\#} with a particular - {\texttt Compact#} at any given time. The primop does not + {\texttt Compact\#} at any given time. The primop does not enforce any mutual exclusion; the caller is expected to arrange this. } with @@ -3076,7 +3092,8 @@ primop CompactAddWithSharing "compactAddWithSharing#" GenPrimOp primop CompactSize "compactSize#" GenPrimOp Compact# -> State# RealWorld -> (# State# RealWorld, Word# #) - { Return the size (in bytes) of the total amount of data in the Compact# } + { Return the total capacity (in bytes) of all the compact blocks + in the CNF. } with has_side_effects = True out_of_line = True |