[Git][ghc/ghc][master] [skip ci] Improve the documentation of the CNF primops. In this context, the...
Marge Bot
gitlab at gitlab.haskell.org
Fri Jun 7 14:20:45 UTC 2019
Marge Bot pushed to branch master at Glasgow Haskell Compiler / GHC
Commits:
d3915b30 by Andrew Martin at 2019-06-07T14:20:42Z
[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.
- - - - -
1 changed file:
- compiler/prelude/primops.txt.pp
Changes:
=====================================
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
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/commit/d3915b304f297b8a2534f6abf9c2984837792921
--
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/commit/d3915b304f297b8a2534f6abf9c2984837792921
You're receiving this email because of your account on gitlab.haskell.org.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20190607/45795b17/attachment-0001.html>
More information about the ghc-commits
mailing list