[Guile-commits] 03/08: Update data representation chapter in the manual

[Andy Wingo]

wingo pushed a commit to branch master
in repository guile.

commit 6be54f4526c951ecc6b72359490c55be2320bbac
Author: Andy Wingo <address@hidden>
Date:   Thu Sep 27 13:43:48 2018 +0200

    Update data representation chapter in the manual
    
    * doc/ref/data-rep.texi (The SCM Type in Guile): Refer to scm.h.
    (Relationship Between SCM and scm_t_bits): Better title-case.
    (Immediate Objects): Better title-case.  Prefer "heap object" over
    "cell".
    (Non-Immediate Objects): Better title-case.  Deprecate the concept of
    cells.
    (Allocating Heap Objects): Rename from Allocating Cells.
    (Heap Object Type Information): Rename from Heap Cell Type Information.
    (Accessing Heap Object Fields): Rename from Accessing Cell Entries.
    * doc/ref/vm.texi: Update references.
---
 doc/ref/data-rep.texi | 279 ++++++++++++++++++++++++--------------------------
 doc/ref/vm.texi       |   4 +-
 2 files changed, 133 insertions(+), 150 deletions(-)

diff --git a/doc/ref/data-rep.texi b/doc/ref/data-rep.texi
index 32c337d..7099c87 100644
--- a/doc/ref/data-rep.texi
+++ b/doc/ref/data-rep.texi
@@ -365,24 +365,24 @@ in question is stored in that data.
 
 This section describes how the @code{SCM} type is actually represented
 and used at the C level. Interested readers should see
address@hidden/tags.h} for an exposition of how Guile stores type
address@hidden/scm.h} for an exposition of how Guile stores type
 information.
 
 In fact, there are two basic C data types to represent objects in
 Guile: @code{SCM} and @code{scm_t_bits}.
 
 @menu
-* Relationship between SCM and scm_t_bits::
-* Immediate objects::
-* Non-immediate objects::
-* Allocating Cells::
-* Heap Cell Type Information::
-* Accessing Cell Entries::
+* Relationship Between SCM and scm_t_bits::
+* Immediate Objects::
+* Non-Immediate Objects::
+* Allocating Heap Objects::
+* Heap Object Type Information::
+* Accessing Heap Object Fields::
 @end menu
 
 
address@hidden Relationship between SCM and scm_t_bits
address@hidden Relationship between @code{SCM} and @code{scm_t_bits}
address@hidden Relationship Between SCM and scm_t_bits
address@hidden Relationship Between @code{SCM} and @code{scm_t_bits}
 
 A variable of type @code{SCM} is guaranteed to hold a valid Scheme
 object.  A variable of type @code{scm_t_bits}, on the other hand, may
@@ -402,19 +402,20 @@ chapter (@pxref{Cheaper Pairs}).  Conversely, a valid bit 
encoding of a
 Scheme value as a @code{scm_t_bits} variable can be transformed into the
 corresponding @code{SCM} value using the @code{SCM_PACK} macro.
 
address@hidden Immediate objects
address@hidden Immediate objects
address@hidden Immediate Objects
address@hidden Immediate Objects
 
-A Scheme object may either be an immediate, i.e.@: carrying all necessary
-information by itself, or it may contain a reference to a @dfn{cell}
-with additional information on the heap.  Although in general it should
-be irrelevant for user code whether an object is an immediate or not,
-within Guile's own code the distinction is sometimes of importance.
-Thus, the following low level macro is provided:
+A Scheme object may either be an immediate, i.e.@: carrying all
+necessary information by itself, or it may contain a reference to a
address@hidden object} which is, as the name implies, data on the heap.
+Although in general it should be irrelevant for user code whether an
+object is an immediate or not, within Guile's own code the distinction
+is sometimes of importance.  Thus, the following low level macro is
+provided:
 
 @deftypefn Macro int SCM_IMP (SCM @var{x})
 A Scheme object is an immediate if it fulfills the @code{SCM_IMP}
-predicate, otherwise it holds an encoded reference to a heap cell.  The
+predicate, otherwise it holds an encoded reference to a heap object.  The
 result of the predicate is delivered as a C style boolean value.  User
 code and code that extends Guile should normally not be required to use
 this macro.
@@ -475,67 +476,88 @@ to us.
 @end deftypefn
 
 
address@hidden Non-immediate objects
address@hidden Non-immediate objects
address@hidden Non-Immediate Objects
address@hidden Non-Immediate Objects
 
 A Scheme object of type @code{SCM} that does not fulfill the
address@hidden predicate holds an encoded reference to a heap cell.
-This reference can be decoded to a C pointer to a heap cell using the
address@hidden macro.  The encoding of a pointer to a heap cell into a
address@hidden value is done using the @code{PTR2SCM} macro.
-
address@hidden (FIXME:: this name should be changed)
address@hidden Macro {scm_t_cell *} SCM2PTR (SCM @var{x})
-Extract and return the heap cell pointer from a non-immediate @code{SCM}
-object @var{x}.
address@hidden predicate holds an encoded reference to a heap object.
+This reference can be decoded to a C pointer to a heap object using the
address@hidden macro.  The encoding of a pointer to a heap
+object into a @code{SCM} value is done using the @code{SCM_PACK_POINTER}
+macro.
+
address@hidden cells, deprecated concept
+Before Guile 2.0, Guile had a custom garbage collector that allocated
+heap objects in units of 2-word @dfn{cells}.  With the move to the
+BDW-GC collector in Guile 2.0, Guile can allocate heap objects of any
+size, and the concept of a cell is now obsolete.  Still, we mention
+it here as the name stil appears in various low-level interfaces.
+
address@hidden Macro {scm_t_bits *} SCM_UNPACK_POINTER (SCM @var{x})
address@hidden Macro {scm_t_cell *} SCM2PTR (SCM @var{x})
+Extract and return the heap object pointer from a non-immediate
address@hidden object @var{x}.  The name @code{SCM2PTR} is deprecated but
+still common.
 @end deftypefn
 
address@hidden (FIXME:: this name should be changed)
address@hidden Macro SCM PTR2SCM (scm_t_cell * @var{x})
-Return a @code{SCM} value that encodes a reference to the heap cell
-pointer @var{x}.
address@hidden Macro SCM_PACK_POINTER (scm_t_bits * @var{x})
address@hidden Macro SCM PTR2SCM (scm_t_cell * @var{x})
+Return a @code{SCM} value that encodes a reference to the heap object
+pointer @var{x}.  The name @code{PTR2SCM} is deprecated but still
+common.
 @end deftypefn
 
 Note that it is also possible to transform a non-immediate @code{SCM}
 value by using @code{SCM_UNPACK} into a @code{scm_t_bits} variable.
 However, the result of @code{SCM_UNPACK} may not be used as a pointer to
-a @code{scm_t_cell}: only @code{SCM2PTR} is guaranteed to transform a
address@hidden object into a valid pointer to a heap cell.  Also, it is not
-allowed to apply @code{PTR2SCM} to anything that is not a valid pointer
-to a heap cell.
+a heap object: only @code{SCM_UNPACK_POINTER} is guaranteed to transform
+a @code{SCM} object into a valid pointer to a heap object.  Also, it is
+not allowed to apply @code{SCM_PACK_POINTER} to anything that is not a
+valid pointer to a heap object.
 
 @noindent
 Summary:  
 @itemize @bullet
 @item
-Only use @code{SCM2PTR} on @code{SCM} values for which @code{SCM_IMP} is
-false!
+Only use @code{SCM_UNPACK_POINTER} on @code{SCM} values for which
address@hidden is false!
 @item
-Don't use @code{(scm_t_cell *) SCM_UNPACK (@var{x})}!  Use @code{SCM2PTR
-(@var{x})} instead!
+Don't use @code{(scm_t_cell *) SCM_UNPACK (@var{x})}!  Use
address@hidden (@var{x})} instead!
 @item
-Don't use @code{PTR2SCM} for anything but a cell pointer!
+Don't use @code{SCM_PACK_POINTER} for anything but a heap object pointer!
 @end itemize
 
address@hidden Allocating Cells
address@hidden Allocating Cells
address@hidden Allocating Heap Objects
address@hidden Allocating Heap Objects
 
-Guile provides both ordinary cells with two slots, and double cells
-with four slots.  The following two function are the most primitive
-way to allocate such cells.
+Heap objects are heap-allocated data pointed to by non-immediate
address@hidden value.  The first word of the heap object should contain a
+type code.  The object may be any number of words in length, and is
+generally scanned by the garbage collector for additional unless the
+object was allocated using a ``pointerless'' allocation function.
 
-If the caller intends to use it as a header for some other type, she
-must pass an appropriate magic value in @var{word_0}, to mark it as a
-member of that type, and pass whatever value as @var{word_1}, etc that
-the type expects.  You should generally not need these functions,
-unless you are implementing a new datatype, and thoroughly understand
-the code in @code{<libguile/tags.h>}.
+You should generally not need these functions, unless you are
+implementing a new data type, and thoroughly understand the code in
address@hidden<libguile/scm.h>}.
 
 If you just want to allocate pairs, use @code{scm_cons}.
 
address@hidden Function SCM scm_words (scm_t_bits word_0, uint32_t n_words)
+Allocate a new heap object containing @var{n_words}, and initialize the
+first slot to @var{word_0}, and return a non-immediate @code{SCM} value
+encoding a pointer to the object.  Typically @var{word_0} will contain
+the type tag.
address@hidden deftypefn
+
+There are also deprecated but common variants of @code{scm_words} that
+use the term ``cell'' to indicate 2-word objects.
+
 @deftypefn Function SCM scm_cell (scm_t_bits word_0, scm_t_bits word_1)
-Allocate a new cell, initialize the two slots with @var{word_0} and
address@hidden, and return it.
+Allocate a new 2-word heap object, initialize the two slots with
address@hidden and @var{word_1}, and return it.  Just like calling
address@hidden (@var{word_0}, 2)}, then initializing the second slot to
address@hidden
 
 Note that @var{word_0} and @var{word_1} are of type @code{scm_t_bits}.
 If you want to pass a @code{SCM} object, you need to use
@@ -543,123 +565,80 @@ If you want to pass a @code{SCM} object, you need to use
 @end deftypefn
 
 @deftypefn Function SCM scm_double_cell (scm_t_bits word_0, scm_t_bits word_1, 
scm_t_bits word_2, scm_t_bits word_3)
-Like @code{scm_cell}, but allocates a double cell with four
-slots.
+Like @code{scm_cell}, but allocates a 4-word heap object.
 @end deftypefn
 
address@hidden Heap Cell Type Information
address@hidden Heap Cell Type Information
address@hidden Heap Object Type Information
address@hidden Heap Object Type Information
 
-Heap cells contain a number of entries, each of which is either a scheme
-object of type @code{SCM} or a raw C value of type @code{scm_t_bits}.
-Which of the cell entries contain Scheme objects and which contain raw C
-values is determined by the first entry of the cell, which holds the
-cell type information.
+Heap objects contain a type tag and are followed by a number of
+word-sized slots.  The interpretation of the object contents depends on
+the type of the object.
 
 @deftypefn Macro scm_t_bits SCM_CELL_TYPE (SCM @var{x})
-For a non-immediate Scheme object @var{x}, deliver the content of the
-first entry of the heap cell referenced by @var{x}.  This value holds
-the information about the cell type.
+Extract the first word of the heap object pointed to by @var{x}.  This
+value holds the information about the cell type.
 @end deftypefn
 
 @deftypefn Macro void SCM_SET_CELL_TYPE (SCM @var{x}, scm_t_bits @var{t})
 For a non-immediate Scheme object @var{x}, write the value @var{t} into
-the first entry of the heap cell referenced by @var{x}.  The value
+the first word of the heap object referenced by @var{x}.  The value
 @var{t} must hold a valid cell type.
 @end deftypefn
 
 
address@hidden Accessing Cell Entries
address@hidden Accessing Cell Entries
address@hidden Accessing Heap Object Fields
address@hidden Accessing Heap Object Fields
 
 For a non-immediate Scheme object @var{x}, the object type can be
-determined by reading the cell type entry using the @code{SCM_CELL_TYPE}
-macro.  For each different type of cell it is known which cell entries
-hold Scheme objects and which cell entries hold raw C data.  To access
-the different cell entries appropriately, the following macros are
-provided.
+determined by using the @code{SCM_CELL_TYPE} macro described in the
+previous section.  For each different type of heap object it is known
+which fields hold tagged Scheme objects and which fields hold untagged
+raw data.  To access the different fields appropriately, the following
+macros are provided.
 
 @deftypefn Macro scm_t_bits SCM_CELL_WORD (SCM @var{x}, unsigned int @var{n})
-Deliver the cell entry @var{n} of the heap cell referenced by the
-non-immediate Scheme object @var{x} as raw data.  It is illegal, to
-access cell entries that hold Scheme objects by using these macros.  For
-convenience, the following macros are also provided.
address@hidden @bullet
address@hidden
-SCM_CELL_WORD_0 (@var{x}) @result{} SCM_CELL_WORD (@var{x}, 0)
address@hidden
-SCM_CELL_WORD_1 (@var{x}) @result{} SCM_CELL_WORD (@var{x}, 1)
address@hidden
address@hidden
address@hidden
address@hidden (@var{x}) @result{} SCM_CELL_WORD (@var{x}, @var{n})
address@hidden itemize
address@hidden Macro scm_t_bits SCM_CELL_WORD_0 (@var{x})
address@hidden Macro scm_t_bits SCM_CELL_WORD_1 (@var{x})
address@hidden Macro scm_t_bits SCM_CELL_WORD_2 (@var{x})
address@hidden Macro scm_t_bits SCM_CELL_WORD_3 (@var{x})
+Deliver the field @var{n} of the heap object referenced by the
+non-immediate Scheme object @var{x} as raw untagged data.  Only use this
+macro for fields containing untagged data; don't use it for fields
+containing tagged @code{SCM} objects.
 @end deftypefn
 
 @deftypefn Macro SCM SCM_CELL_OBJECT (SCM @var{x}, unsigned int @var{n})
-Deliver the cell entry @var{n} of the heap cell referenced by the
-non-immediate Scheme object @var{x} as a Scheme object.  It is illegal,
-to access cell entries that do not hold Scheme objects by using these
-macros.  For convenience, the following macros are also provided.
address@hidden @bullet
address@hidden
-SCM_CELL_OBJECT_0 (@var{x}) @result{} SCM_CELL_OBJECT (@var{x}, 0)
address@hidden
-SCM_CELL_OBJECT_1 (@var{x}) @result{} SCM_CELL_OBJECT (@var{x}, 1)
address@hidden
address@hidden
address@hidden
address@hidden (@var{x}) @result{} SCM_CELL_OBJECT (@var{x},
address@hidden)
address@hidden itemize
address@hidden Macro SCM SCM_CELL_OBJECT_0 (SCM @var{x})
address@hidden Macro SCM SCM_CELL_OBJECT_1 (SCM @var{x})
address@hidden Macro SCM SCM_CELL_OBJECT_2 (SCM @var{x})
address@hidden Macro SCM SCM_CELL_OBJECT_3 (SCM @var{x})
+Deliver the field @var{n} of the heap object referenced by the
+non-immediate Scheme object @var{x} as a Scheme object.  Only use this
+macro for fields containing tagged @code{SCM} objects; don't use it for
+fields containing untagged data.
 @end deftypefn
 
 @deftypefn Macro void SCM_SET_CELL_WORD (SCM @var{x}, unsigned int @var{n}, 
scm_t_bits @var{w})
-Write the raw C value @var{w} into entry number @var{n} of the heap cell
address@hidden Macro void SCM_SET_CELL_WORD_0 (@var{x}, @var{w})
address@hidden Macro void SCM_SET_CELL_WORD_1 (@var{x}, @var{w})
address@hidden Macro void SCM_SET_CELL_WORD_2 (@var{x}, @var{w})
address@hidden Macro void SCM_SET_CELL_WORD_3 (@var{x}, @var{w})
+Write the raw value @var{w} into field number @var{n} of the heap object
 referenced by the non-immediate Scheme value @var{x}.  Values that are
-written into cells this way may only be read from the cells using the
address@hidden macros or, in case cell entry 0 is written, using
-the @code{SCM_CELL_TYPE} macro.  For the special case of cell entry 0 it
-has to be made sure that @var{w} contains a cell type information which
-does not describe a Scheme object.  For convenience, the following
-macros are also provided.
address@hidden @bullet
address@hidden
-SCM_SET_CELL_WORD_0 (@var{x}, @var{w}) @result{} SCM_SET_CELL_WORD
-(@var{x}, 0, @var{w})
address@hidden
-SCM_SET_CELL_WORD_1 (@var{x}, @var{w}) @result{} SCM_SET_CELL_WORD
-(@var{x}, 1, @var{w})
address@hidden
address@hidden
address@hidden
address@hidden (@var{x}, @var{w}) @result{} SCM_SET_CELL_WORD
-(@var{x}, @var{n}, @var{w})
address@hidden itemize
+written into heap objects as raw values should only be read later using
+the @code{SCM_CELL_WORD} macros.
 @end deftypefn
 
 @deftypefn Macro void SCM_SET_CELL_OBJECT (SCM @var{x}, unsigned int @var{n}, 
SCM @var{o})
-Write the Scheme object @var{o} into entry number @var{n} of the heap
-cell referenced by the non-immediate Scheme value @var{x}.  Values that
-are written into cells this way may only be read from the cells using
-the @code{SCM_CELL_OBJECT} macros or, in case cell entry 0 is written,
-using the @code{SCM_CELL_TYPE} macro.  For the special case of cell
-entry 0 the writing of a Scheme object into this cell is only allowed
-if the cell forms a Scheme pair.  For convenience, the following macros
-are also provided.
address@hidden @bullet
address@hidden
-SCM_SET_CELL_OBJECT_0 (@var{x}, @var{o}) @result{} SCM_SET_CELL_OBJECT
-(@var{x}, 0, @var{o})
address@hidden
-SCM_SET_CELL_OBJECT_1 (@var{x}, @var{o}) @result{} SCM_SET_CELL_OBJECT
-(@var{x}, 1, @var{o})
address@hidden
address@hidden
address@hidden
address@hidden (@var{x}, @var{o}) @result{}
-SCM_SET_CELL_OBJECT (@var{x}, @var{n}, @var{o})
address@hidden itemize
address@hidden Macro void SCM_SET_CELL_OBJECT_0 (SCM @var{x}, SCM @var{o})
address@hidden Macro void SCM_SET_CELL_OBJECT_1 (SCM @var{x}, SCM @var{o})
address@hidden Macro void SCM_SET_CELL_OBJECT_2 (SCM @var{x}, SCM @var{o})
address@hidden Macro void SCM_SET_CELL_OBJECT_3 (SCM @var{x}, SCM @var{o})
+Write the Scheme object @var{o} into field number @var{n} of the heap
+object referenced by the non-immediate Scheme value @var{x}.  Values
+that are written into heap objects as objects should only be read using
+the @code{SCM_CELL_OBJECT} macros.
 @end deftypefn
 
 @noindent
@@ -669,9 +648,13 @@ Summary:
 For a non-immediate Scheme object @var{x} of unknown type, get the type
 information by using @code{SCM_CELL_TYPE (@var{x})}.
 @item
-As soon as the cell type information is available, only use the
-appropriate access methods to read and write data to the different cell
-entries.
+As soon as the type information is available, only use the appropriate
+access methods to read and write data to the different heap object
+fields.
address@hidden
+Note that field 0 stores the cell type information.  Generally speaking,
+other data associated with a heap object is stored starting from field
+1.
 @end itemize
 
 
diff --git a/doc/ref/vm.texi b/doc/ref/vm.texi
index 35de1da..7ff247f 100644
--- a/doc/ref/vm.texi
+++ b/doc/ref/vm.texi
@@ -272,7 +272,7 @@ program)}.  @xref{Compiled Procedures}, for a full API 
reference.
 
 A procedure may reference data that was statically allocated when the
 procedure was compiled.  For example, a pair of immediate objects
-(@pxref{Immediate objects}) can be allocated directly in the memory
+(@pxref{Immediate Objects}) can be allocated directly in the memory
 segment that contains the compiled bytecode, and accessed directly by
 the bytecode.
 
@@ -495,7 +495,7 @@ An offset from the current @code{ip}, in 32-bit units, as a 
signed
 24-bit value.  Indicates a bytecode address, for a relative jump.
 @item i16
 @itemx i32
-An immediate Scheme value (@pxref{Immediate objects}), encoded directly
+An immediate Scheme value (@pxref{Immediate Objects}), encoded directly
 in 16 or 32 bits.
 @item a32
 @itemx b32