@c essay @sp 10
@c essay @comment The title is printed in a large font.
@c essay @title Data Representation in Guile
-@c essay @subtitle $Id: data-rep.texi,v 1.1 2001-08-24 09:40:29 ossau Exp $
+@c 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
The complement of SCM_CONSP.
@end deftypefn
-@deftypefn 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
-@code{<libguile/tags.h>}.
-@end 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.
the @code{SCM} type with utility functions and macros.
@item
-@code{scm_bits_t} is an integral data type that is guaranteed to be
+@code{scm_t_bits} 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
@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
-@node Relationship between SCM and scm_bits_t
-@subsubsection Relationship between @code{SCM} and @code{scm_bits_t}
+@node Relationship between SCM and scm_t_bits
+@subsubsection 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.
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.
-@deftypefn Macro scm_bits_t SCM_UNPACK (SCM @var{x})
+@deftypefn 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
-@deftypefn Macro SCM SCM_PACK (scm_bits_t @var{x})
+@deftypefn 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
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
-@code{scm_bits_t} value that is delivered by @code{SCM_UNPACK
+@code{scm_t_bits} value that is delivered by @code{SCM_UNPACK
(@var{x})}.
@end itemize
@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
Don't use @code{PTR2SCM} for anything but a cell pointer!
@end itemize
+@node Allocating Cells
+@subsubsection 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}.
+
+@deftypefn 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
+@var{word_1}, 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
+@code{SCM_UNPACK}.
+@end deftypefn
+
+@deftypefn 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.
+@end 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.
-@deftypefn Macro scm_bits_t SCM_CELL_TYPE (SCM @var{x})
+@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.
@end deftypefn
-@deftypefn Macro void SCM_SET_CELL_TYPE (SCM @var{x}, scm_bits_t @var{t})
+@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
@var{t} must hold a valid cell type.
the different cell entries appropriately, the following macros are
provided.
-@deftypefn Macro scm_bits_t SCM_CELL_WORD (SCM @var{x}, unsigned int @var{n})
+@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
@end itemize
@end deftypefn
-@deftypefn Macro void SCM_SET_CELL_WORD (SCM @var{x}, unsigned int @var{n}, scm_bits_t @var{w})
+@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
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
To actually register the new smob type, call @code{scm_make_smob_type}:
-@deftypefun scm_bits_t scm_make_smob_type (const char *name, size_t size)
+@deftypefun 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.
only zero or one time per type, and the call should be placed
immediately following the call to @code{scm_make_smob_type}.
-@deftypefun void scm_set_smob_mark (scm_bits_t tc, SCM (*mark) (SCM))
+@deftypefun 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
-@deftypefun void scm_set_smob_free (scm_bits_t tc, size_t (*free) (SCM))
+@deftypefun 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
-@deftypefun void scm_set_smob_print (scm_bits_t tc, int (*print) (SCM, SCM, scm_print_state*))
+@deftypefun 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
-@deftypefun void scm_set_smob_equalp (scm_bits_t tc, SCM (*equalp) (SCM, SCM))
+@deftypefun 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
@example
#include <libguile.h>
-static scm_bits_t image_tag;
+static scm_t_bits image_tag;
void
init_image_type (void)
@code{SCM_NEWSMOB3} variants will allocate double cells and thus use
twice as much memory as smobs created by @code{SCM_NEWSMOB}.}
-@deftypefn Macro void SCM_NEWSMOB(SCM value, scm_bits_t tag, void *data)
-@deftypefnx Macro void SCM_NEWSMOB2(SCM value, scm_bits_t tag, void *data1, void *data2)
-@deftypefnx Macro void SCM_NEWSMOB3(SCM value, scm_bits_t tag, void *data1, void *data2, void *data3)
+@deftypefn Macro void SCM_NEWSMOB(SCM value, scm_t_bits tag, void *data)
+@deftypefnx Macro void SCM_NEWSMOB2(SCM value, scm_t_bits tag, void *data1, void *data2)
+@deftypefnx 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}.
create a smob instance and return it, there is also a slightly specialized
macro for this situation:
-@deftypefn Macro fn_returns SCM_RETURN_NEWSMOB(scm_bits_t tag, void *data)
-@deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB2(scm_bits_t tag, void *data1, void *data2)
-@deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB3(scm_bits_t tag, void *data1, void *data2, void *data3)
+@deftypefn Macro fn_returns SCM_RETURN_NEWSMOB(scm_t_bits tag, void *data)
+@deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB2(scm_t_bits tag, void *data1, void *data2)
+@deftypefnx 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
#include <stdlib.h>
#include <libguile.h>
-static scm_bits_t image_tag;
+static scm_t_bits image_tag;
struct image @{
int width, height;
HCoop / bpt / guile.git / commitdiff