[skip ci] Improve the documentation of the CNF primops. In this context, the term...
[ghc.git] / compiler / prelude / primops.txt.pp
index eb1e50b..39e7c47 100644 (file)
@@ -33,7 +33,7 @@
 --
 -- The format of each primop entry is as follows:
 --
---      primop internal-name "name-in-program-text" type category {description} attributes
+--      primop internal-name "name-in-program-text" category type {description} attributes
 
 -- The default attribute values which apply if you don't specify
 -- other ones.  Attribute values can be True, False, or arbitrary
@@ -1136,9 +1136,11 @@ primop CasArrayOp  "casArray#" GenPrimOp
    {Given an array, an offset, the expected old value, and
     the new value, perform an atomic compare and swap (i.e. write the new
     value if the current value and the old value are the same pointer).
-    Returns 0 if the swap succeeds and 1 if it fails. Returns the value of
-    the element before the operation. Implies a full memory barrier. The
-    use of a pointer equality on a lifted value makes this function harder
+    Returns 0 if the swap succeeds and 1 if it fails. Additionally, returns
+    the element at the offset after the operation completes. This means that
+    on a success the new value is returned, and on a failure the actual old
+    value (not the expected one) is returned. Implies a full memory barrier.
+    The use of a pointer equality on a lifted value makes this function harder
     to use correctly than {\tt casIntArray\#}. All of the difficulties
     of using {\tt reallyUnsafePtrEquality\#} correctly apply to
     {\tt casArray\#} as well.
@@ -2975,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
@@ -2991,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
@@ -3040,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
@@ -3054,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
@@ -3074,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