guile/guile-core/doc/ref data-rep.texi

[Marius Vollmer]

CVSROOT:        /cvs
Module name:    guile
Changes by:     Marius Vollmer <address@hidden> 01/11/25 09:51:03

Modified files:
        guile-core/doc/ref: data-rep.texi 

Log message:
        Removed docs about SCM_NEWCELL and added scm_alloc_cell and
        scm_alloc_double_cell.
        Replaced scm_bits_t with scm_t_bits.

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/ref/data-rep.texi.diff?cvsroot=OldCVS&tr1=1.1&tr2=1.2&r1=text&r2=text

Patches:
Index: guile/guile-core/doc/ref/data-rep.texi
diff -u guile/guile-core/doc/ref/data-rep.texi:1.1 
guile/guile-core/doc/ref/data-rep.texi:1.2
--- guile/guile-core/doc/ref/data-rep.texi:1.1  Fri Aug 24 05:40:29 2001
+++ guile/guile-core/doc/ref/data-rep.texi      Sun Nov 25 09:51:03 2001
@@ -46,7 +46,7 @@
 @c essay @sp 10
 @c essay @comment The title is printed in a large font.
 @c essay @title Data Representation in Guile
address@hidden essay @subtitle $Id: data-rep.texi,v 1.1 2001/08/24 09:40:29 
ossau Exp $
address@hidden essay @subtitle $Id: data-rep.texi,v 1.2 2001/11/25 14:51:03 mvo 
Exp $
 @c essay @subtitle For use with Guile @value{VERSION}
 @c essay @author Jim Blandy
 @c essay @author Free Software Foundation
@@ -792,25 +792,6 @@
 The complement of SCM_CONSP.
 @end deftypefn
 
address@hidden Macro void SCM_NEWCELL (SCM @var{into})
-Allocate a new cell, and set @var{into} to point to it.  This macro
-expands to a statement, not an expression, and @var{into} must be an
-lvalue of type SCM.
-
-This is the most primitive way to allocate a cell; it is quite fast.
-
-The @sc{car} of the cell initially tags it as a ``free cell''.  If the
-caller intends to use it as an ordinary cons, she must store ordinary
-SCM values in its @sc{car} and @sc{cdr}.
-
-If the caller intends to use it as a header for some other type, she
-must store an appropriate magic value in the cell's @sc{car}, to mark
-it as a member of that type, and store whatever value in the @sc{cdr}
-that type expects.  You should generally not do this, unless you are
-implementing a new datatype, and thoroughly understand the code in
address@hidden<libguile/tags.h>}.
address@hidden deftypefn
-
 @deftypefun SCM scm_cons (SCM @var{car}, SCM @var{cdr})
 Allocate (``CONStruct'') a new pair, with @var{car} and @var{cdr} as its
 contents.
@@ -1077,7 +1058,7 @@
 the @code{SCM} type with utility functions and macros.
 
 @item
address@hidden is an integral data type that is guaranteed to be
address@hidden is an integral data type that is guaranteed to be
 large enough to hold all information that is required to represent any
 Scheme object.  While this data type is mostly used to implement Guile's
 internals, the use of this type is also necessary to write certain kinds
@@ -1085,20 +1066,21 @@
 @end itemize
 
 @menu
-* Relationship between SCM and scm_bits_t::
+* Relationship between SCM and scm_t_bits::
 * Immediate objects::
 * Non-immediate objects::
+* Allocating Cells::
 * Heap Cell Type Information::
 * Accessing Cell Entries::
 * Basic Rules for Accessing Cell Entries::
 @end menu
 
 
address@hidden Relationship between SCM and scm_bits_t
address@hidden Relationship between @code{SCM} and @code{scm_bits_t}
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_bits_t}, on the other hand, may
+object.  A variable of type @code{scm_t_bits}, on the other hand, may
 hold a representation of a @code{SCM} value as a C integral type, but
 may also hold any C value, even if it does not correspond to a valid
 Scheme object.
@@ -1107,21 +1089,21 @@
 information is stored in a form that is not directly usable.  To be able
 to work on the type encoding of the scheme value, the @code{SCM}
 variable has to be transformed into the corresponding representation as
-a @code{scm_bits_t} variable @var{y} by using the @code{SCM_UNPACK}
+a @code{scm_t_bits} variable @var{y} by using the @code{SCM_UNPACK}
 macro.  Once this has been done, the type of the scheme object @var{x}
-can be derived from the content of the bits of the @code{scm_bits_t}
+can be derived from the content of the bits of the @code{scm_t_bits}
 value @var{y}, in the way illustrated by the example earlier in this
 chapter (@pxref{Cheaper Pairs}).  Conversely, a valid bit encoding of a
-Scheme value as a @code{scm_bits_t} variable can be transformed into the
+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 Macro scm_bits_t SCM_UNPACK (SCM @var{x})
address@hidden Macro scm_t_bits SCM_UNPACK (SCM @var{x})
 Transforms the @code{SCM} value @var{x} into its representation as an
 integral type.  Only after applying @code{SCM_UNPACK} it is possible to
 access the bits and contents of the @code{SCM} value.
 @end deftypefn
 
address@hidden Macro SCM SCM_PACK (scm_bits_t @var{x})
address@hidden Macro SCM SCM_PACK (scm_t_bits @var{x})
 Takes a valid integral representation of a Scheme object and transforms
 it into its representation as a @code{SCM} value.
 @end deftypefn
@@ -1153,7 +1135,7 @@
 with @code{SCM_IMP (@var{x})} if it is an immediate object.
 @item
 If so, all of the type and value information can be determined from the
address@hidden value that is delivered by @code{SCM_UNPACK
address@hidden value that is delivered by @code{SCM_UNPACK
 (@var{x})}.
 @end itemize
 
@@ -1180,7 +1162,7 @@
 @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_bits_t} variable.
+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_cell}: only @code{SCM2PTR} is guaranteed to transform a
 @code{SCM} object into a valid pointer to a heap cell.  Also, it is not
@@ -1200,23 +1182,52 @@
 Don't use @code{PTR2SCM} for anything but a cell pointer!
 @end itemize
 
address@hidden Allocating Cells
address@hidden Allocating Cells
+
+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.
+
+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>}.
+
+If you just want to allocate pairs, use @code{scm_cons}.
+
address@hidden Function SCM scm_alloc_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.
+
+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
address@hidden
address@hidden deftypefn
+
address@hidden Function SCM scm_alloc_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_alloc_cell}, but allocates a double cell with four
+slots.
address@hidden deftypefn
 
 @node Heap Cell Type Information
 @subsubsection Heap Cell 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_bits_t}.
+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.
 
address@hidden Macro scm_bits_t SCM_CELL_TYPE (SCM @var{x})
address@hidden 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.
 @end deftypefn
 
address@hidden Macro void SCM_SET_CELL_TYPE (SCM @var{x}, scm_bits_t @var{t})
address@hidden 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
 @var{t} must hold a valid cell type.
@@ -1233,7 +1244,7 @@
 the different cell entries appropriately, the following macros are
 provided.
 
address@hidden Macro scm_bits_t SCM_CELL_WORD (SCM @var{x}, unsigned int 
@var{n})
address@hidden 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
@@ -1268,7 +1279,7 @@
 @end itemize
 @end deftypefn
 
address@hidden Macro void SCM_SET_CELL_WORD (SCM @var{x}, unsigned int @var{n}, 
scm_bits_t @var{w})
address@hidden 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
 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
@@ -1432,7 +1443,7 @@
 
 To actually register the new smob type, call @code{scm_make_smob_type}:
 
address@hidden scm_bits_t scm_make_smob_type (const char *name, size_t size)
address@hidden scm_t_bits scm_make_smob_type (const char *name, size_t size)
 This function implements the standard way of adding a new smob type,
 named @var{name}, with instance size @var{size}, to the system.  The
 return value is a tag that is used in creating instances of the type.
@@ -1451,22 +1462,22 @@
 only zero or one time per type, and the call should be placed
 immediately following the call to @code{scm_make_smob_type}.
 
address@hidden void scm_set_smob_mark (scm_bits_t tc, SCM (*mark) (SCM))
address@hidden void scm_set_smob_mark (scm_t_bits tc, SCM (*mark) (SCM))
 This function sets the smob marking procedure for the smob type specified by
 the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
 @end deftypefun
 
address@hidden void scm_set_smob_free (scm_bits_t tc, size_t (*free) (SCM))
address@hidden void scm_set_smob_free (scm_t_bits tc, size_t (*free) (SCM))
 This function sets the smob freeing procedure for the smob type specified by
 the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
 @end deftypefun
 
address@hidden void scm_set_smob_print (scm_bits_t tc, int (*print) (SCM, SCM, 
scm_print_state*))
address@hidden void scm_set_smob_print (scm_t_bits tc, int (*print) (SCM, SCM, 
scm_print_state*))
 This function sets the smob printing procedure for the smob type specified by
 the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
 @end deftypefun
 
address@hidden void scm_set_smob_equalp (scm_bits_t tc, SCM (*equalp) (SCM, 
SCM))
address@hidden void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM, 
SCM))
 This function sets the smob equality-testing predicate for the smob type 
specified by
 the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
 @end deftypefun
@@ -1500,7 +1511,7 @@
 @example
 #include <libguile.h>
 
-static scm_bits_t image_tag;
+static scm_t_bits image_tag;
 
 void
 init_image_type (void)
@@ -1529,9 +1540,9 @@
 @code{SCM_NEWSMOB3} variants will allocate double cells and thus use
 twice as much memory as smobs created by @code{SCM_NEWSMOB}.}
 
address@hidden Macro void SCM_NEWSMOB(SCM value, scm_bits_t tag, void *data)
address@hidden Macro void SCM_NEWSMOB2(SCM value, scm_bits_t tag, void *data1, 
void *data2)
address@hidden Macro void SCM_NEWSMOB3(SCM value, scm_bits_t tag, void *data1, 
void *data2, void *data3)
address@hidden Macro void SCM_NEWSMOB(SCM value, scm_t_bits tag, void *data)
address@hidden Macro void SCM_NEWSMOB2(SCM value, scm_t_bits tag, void *data1, 
void *data2)
address@hidden Macro void SCM_NEWSMOB3(SCM value, scm_t_bits tag, void *data1, 
void *data2, void *data3)
 Make @var{value} contain a smob instance of the type with tag @var{tag}
 and smob data @var{data} (or @var{data1}, @var{data2}, and @var{data3}).
 @var{value} must be previously declared as C type @code{SCM}.
@@ -1541,9 +1552,9 @@
 create a smob instance and return it, there is also a slightly specialized
 macro for this situation:
 
address@hidden Macro fn_returns SCM_RETURN_NEWSMOB(scm_bits_t tag, void *data)
address@hidden Macro fn_returns SCM_RETURN_NEWSMOB2(scm_bits_t tag, void 
*data1, void *data2)
address@hidden Macro fn_returns SCM_RETURN_NEWSMOB3(scm_bits_t tag, void 
*data1, void *data2, void *data3)
address@hidden Macro fn_returns SCM_RETURN_NEWSMOB(scm_t_bits tag, void *data)
address@hidden Macro fn_returns SCM_RETURN_NEWSMOB2(scm_t_bits tag, void 
*data1, void *data2)
address@hidden Macro fn_returns SCM_RETURN_NEWSMOB3(scm_t_bits tag, void 
*data1, void *data2, void *data3)
 This macro expands to a block of code that creates a smob instance of
 the type with tag @var{tag} and smob data @var{data} (or @var{data1},
 @var{data2}, and @var{data3}), and returns that @code{SCM} value.  It
@@ -1942,7 +1953,7 @@
 #include <stdlib.h>
 #include <libguile.h>
 
-static scm_bits_t image_tag;
+static scm_t_bits image_tag;
 
 struct image @{
   int width, height;