mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-04-30 03:40:34 +02:00
228a24ef30
* api.txt, data-rep.texi: Renamed the struct scm_cell to scm_t_cell. * data-rep.texi: Renamed scm_alloc_cell to scm_cell and scm_alloc_double_cell to scm_double_cell. Changes in libguile: * gc.c (SCM_HEAP_SEG_SIZE, CELL_UP, CELL_DN, NEXT_DATA_CELL, init_heap_seg, alloc_some_heap), gc.h (struct scm_cell, struct scm_t_cell, SCM_CELLPTR, SCM_GC_CARD_SIZE, SCM_GC_IN_CARD_HEADERP), tags.h (SCM_CELLP): Renamed the struct scm_cell and all its uses to scm_t_cell in accordance to Guile's naming scheme for types. * alist.c (scm_acons), convert.i.c (CTYPES2UVECT, CTYPES2UVECT_OPTIONAL), coop-threads.c (scm_call_with_new_thread, scm_spawn_thread), debug.c (scm_make_debugobj), environments.c (scm_make_environment), eval.c (scm_closure), fports.c (scm_fdes_to_port), gc.c (scm_deprecated_newcell, scm_deprecated_newcell2), inline.h (scm_alloc_cell, scm_cell), list.c (SCM_I_CONS), numbers.c (scm_i_mkbig), pairs.c (scm_cons), ports.c (scm_void_port), procs.c (scm_c_make_subr, scm_makcclo), smob.c (scm_make_smob), smob.h (SCM_NEWSMOB), strings.c (scm_take_str, scm_allocate_string), strports.c (scm_mkstrport), unif.c (scm_make_uve), variable.c (make_variable), vectors.c (scm_c_make_vector), vports.c (scm_make_soft_port): Renamed scm_alloc_cell to scm_cell. * environments.c (core_environments_observe), gc.c (scm_deprecated_newcell2), goops.c (wrap_init, scm_wrap_object), inline.h (scm_alloc_double_cell, scm_double_cell), num2float.i.c (FLOAT2NUM), numbers.c (scm_make_real), procs.c (scm_make_procedure_with_setter), smob.h (SCM_NEWSMOB2, SCM_NEWSMOB3), struct.c (scm_make_struct, scm_make_vtable_vtable), symbols.c (scm_mem2symbol, scm_mem2uninterned_symbol), weaks.c (allocate_weak_vector): Renamed scm_alloc_double_cell to scm_double_cell.
185 lines
9 KiB
Text
185 lines
9 KiB
Text
Scheme objects
|
|
==============
|
|
|
|
There are two basic C data types to represent objects in guile:
|
|
|
|
- SCM: SCM is the user level abstract C type that is used to represent all of
|
|
guile's scheme objects, no matter what the scheme object type is. No C
|
|
operation except assignment is guaranteed to work with variables of type SCM.
|
|
Only use macros and functions to work with SCM values. Values are converted
|
|
between C data types and the SCM type with utility functions and macros.
|
|
|
|
- scm_bits_t: 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 used to implement guile internals, the use of this type is
|
|
also necessary to write certain kinds of extensions to guile.
|
|
|
|
|
|
Relationship between SCM and scm_bits_t
|
|
=======================================
|
|
|
|
A variable of type SCM is guaranteed to hold a valid scheme object. A
|
|
variable of type scm_bits_t, however, may either hold a representation of a
|
|
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.
|
|
|
|
For a variable x of type SCM, the scheme object's type 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 SCM variable has to be transformed into the
|
|
corresponding representation as a scm_bits_t variable y by using the
|
|
SCM_UNPACK macro. After this has been done, the type of the scheme object x
|
|
can be derived from the content of the bits of the scm_bits_t value y, as is
|
|
described in -->data-rep. A valid bit encoding of a scheme value as a
|
|
scm_bits_t variable can be transformed into the corresponding SCM value by
|
|
using the SCM_PACK macro.
|
|
|
|
- scm_bits_t SCM_UNPACK (SCM x): Transforms the SCM value x into it's
|
|
representation as an integral type. Only after applying SCM_UNPACK it is
|
|
possible to access the bits and contents of the SCM value.
|
|
|
|
- SCM SCM_PACK (scm_bits_t x): Takes a valid integral representation of a
|
|
scheme object and transforms it into its representation as a SCM value.
|
|
|
|
|
|
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 'cell' with
|
|
additional information on the heap. While the fact, whether an object is an
|
|
immediate or not should be irrelevant for user code, within guile's own code
|
|
the distinction is sometimes of importance. Thus, the following low level
|
|
macro is provided:
|
|
|
|
- int SCM_IMP (SCM x): A scheme object is an immediate if it fullfills the
|
|
SCM_IMP predicate, otherwise it holds an encoded reference to a heap cell.
|
|
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.
|
|
|
|
Summary:
|
|
* For a scheme object x of unknown type, check first with SCM_IMP (x) if it is
|
|
an immediate object. If so, all of the type and value information can be
|
|
determined from the scm_bits_t value that is delivered by SCM_UNPACK (x).
|
|
|
|
|
|
Non immediate objects
|
|
=====================
|
|
|
|
- (scm_t_cell *) SCM2PTR (SCM x) (FIXME:: this name should be changed)
|
|
- SCM PTR2SCM (scm_t_cell * x) (FIXME:: this name should be changed)
|
|
|
|
A scheme object of type SCM that does not fullfill the SCM_IMP predicate holds
|
|
an encoded reference to a heap cell. This reference can be decoded to a C
|
|
pointer to a heap cell using the SCM2PTR macro. The encoding of a pointer to
|
|
a heap cell into a SCM value is done using the PTR2SCM macro.
|
|
|
|
Note that it is also possible to transform a non immediate SCM value by using
|
|
SCM_UNPACK into a scm_bits_t variable. Hower, the result of SCM_UNPACK may
|
|
not be used as a pointer to a scm_t_cell: Only SCM2PTR is guaranteed to
|
|
transform a SCM object into a valid pointer to a heap cell. Also, it is not
|
|
allowed to apply PTR2SCM to anything that is not a valid pointer to a heap
|
|
cell.
|
|
|
|
Summary:
|
|
* Only use SCM2PTR for SCM values for which SCM_IMP is false!
|
|
* Don't use '(scm_t_cell*) SCM_UNPACK (x)'! Use 'SCM2PTR (x)' instead!
|
|
* Don't use PTR2SCM for anything but a cell pointer!
|
|
|
|
|
|
Heap Cell Type Information
|
|
==========================
|
|
|
|
Heap cells contain a number of entries, each of which is either a scheme
|
|
object of type SCM or a raw C value of type scm_bits_t. 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.
|
|
|
|
- scm_bits_t SCM_CELL_TYPE (SCM x): For a non immediate scheme object x,
|
|
deliver the content of the first entry of the heap cell referenced by x. This
|
|
value holds the information about the cell type as described in -->data-rep.
|
|
|
|
- void SCM_SET_CELL_TYPE (SCM x, scm_bits_t t): For a non immediate scheme
|
|
object x, write the value t into the first entry of the heap cell referenced
|
|
by x. The value t must hold a valid cell type as described in -->data-rep.
|
|
|
|
|
|
Accessing Cell Entries
|
|
======================
|
|
|
|
For a non immediate scheme object x, the object type can be determined by
|
|
reading the cell type entry using the SCM_CELL_TYPE macro. For the different
|
|
types of cells it is known which cell entry holds scheme objects and which cell
|
|
entry holds raw C data. To access the different cell entries appropriately,
|
|
the following macros are provided:
|
|
|
|
- scm_bits_t SCM_CELL_WORD (SCM x, unsigned int n): Deliver the cell entry n
|
|
of the heap cell referenced by the non immediate scheme object 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:
|
|
SCM_CELL_WORD_0 (x) --> SCM_CELL_WORD (x, 0)
|
|
SCM_CELL_WORD_1 (x) --> SCM_CELL_WORD (x, 1)
|
|
...
|
|
SCM_CELL_WORD_n (x) --> SCM_CELL_WORD (x, n)
|
|
|
|
- SCM SCM_CELL_OBJECT (SCM x, unsigned int n): Deliver the cell entry n of
|
|
the heap cell referenced by the non immediate scheme object 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:
|
|
SCM_CELL_OBJECT_0 (x) --> SCM_CELL_OBJECT (x, 0)
|
|
SCM_CELL_OBJECT_1 (x) --> SCM_CELL_OBJECT (x, 1)
|
|
...
|
|
SCM_CELL_OBJECT_n (x) --> SCM_CELL_OBJECT (x, n)
|
|
|
|
- void SCM_SET_CELL_WORD (SCM x, unsigned int n, scm_bits_t w): Write the raw
|
|
C value w into entry number n of the heap cell referenced by the non immediate
|
|
scheme value x. Values that are written into cells this way may only be read
|
|
from the cells using the SCM_CELL_WORD macros or, in case cell entry 0 is
|
|
written, using the SCM_CELL_TYPE macro. For the special case of cell entry 0
|
|
it has to be made sure that w contains a cell type information (see
|
|
-->data-rep) which does not describe a scheme object. For convenience, the
|
|
following macros are also provided:
|
|
SCM_SET_CELL_WORD_0 (x, w) --> SCM_SET_CELL_WORD (x, 0, w)
|
|
SCM_SET_CELL_WORD_1 (x, w) --> SCM_SET_CELL_WORD (x, 1, w)
|
|
...
|
|
SCM_SET_CELL_WORD_n (x, w) --> SCM_SET_CELL_WORD (x, n, w)
|
|
|
|
- void SCM_SET_CELL_OBJECT (SCM x, unsigned int n, SCM o): Write the scheme
|
|
object o into entry number n of the heap cell referenced by the non immediate
|
|
scheme value x. Values that are written into cells this way may only be read
|
|
from the cells using the SCM_CELL_OBJECT macros or, in case cell entry 0 is
|
|
written, using the 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:
|
|
SCM_SET_CELL_OBJECT_0 (x, o) --> SCM_SET_CELL_OBJECT (x, 0, o)
|
|
SCM_SET_CELL_OBJECT_1 (x, o) --> SCM_SET_CELL_OBJECT (x, 1, o)
|
|
...
|
|
SCM_SET_CELL_OBJECT_n (x, o) --> SCM_SET_CELL_OBJECT (x, n, o)
|
|
|
|
Summary:
|
|
* For a non immediate scheme object x of unknown type, get the type
|
|
information by using SCM_CELL_TYPE (x).
|
|
* 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.
|
|
|
|
|
|
Basic Rules for Accessing Cell Entries
|
|
======================================
|
|
|
|
For each cell type it is generally up to the implementation of that type which
|
|
of the corresponding cell entries hold scheme objects and which hold raw C
|
|
values. However, there is one basic rules that has to be followed: Scheme
|
|
pairs consist of exactly two cell entries, which both contain scheme objects.
|
|
Further, a cell which contains a scheme object in it first entry has to be a
|
|
scheme pair. In other words, it is not allowed to store a scheme object in
|
|
the first cell entry and a non scheme object in the second cell entry.
|
|
|
|
Fixme:shouldn't this rather be SCM_PAIRP / SCM_PAIR_P ?
|
|
- int SCM_CONSP (SCM x): Determine, whether the scheme object x is a scheme
|
|
pair, i. e. whether x references a heap cell consisting of exactly two
|
|
entries, where both entries contain a scheme object. In this case, both
|
|
entries will have to be accessed using the SCM_CELL_OBJECT macros. On the
|
|
contrary, if the SCM_CONSP predicate is not fulfilled, the first entry of the
|
|
scheme cell is guaranteed not to be a scheme value and thus the first cell
|
|
entry must be accessed using the SCM_CELL_WORD_0 macro.
|