doc/ref/api.txt

   1 Scheme objects
   2 ==============
   3
   4 There are two basic C data types to represent objects in guile:
   5
   6 - SCM:  SCM is the user level abstract C type that is used to represent all of
   7 guile's scheme objects, no matter what the scheme object type is.  No C
   8 operation except assignment is guaranteed to work with variables of type SCM.
   9 Only use macros and functions to work with SCM values.  Values are converted
  10 between C data types and the SCM type with utility functions and macros.
  11
  12 - scm_bits_t:  An integral data type that is guaranteed to be large enough to
  13 hold all information that is required to represent any scheme object.  While
  14 this data type is used to implement guile internals, the use of this type is
  15 also necessary to write certain kinds of extensions to guile.
  16
  17
  18 Relationship between SCM and scm_bits_t
  19 =======================================
  20
  21 A variable of type SCM is guaranteed to hold a valid scheme object.  A
  22 variable of type scm_bits_t, however, may either hold a representation of a
  23 SCM value as a C integral type, but may also hold any C value, even if it does
  24 not correspond to a valid scheme object.
  25
  26 For a variable x of type SCM, the scheme object's type information is stored
  27 in a form that is not directly usable.  To be able to work on the type
  28 encoding of the scheme value, the SCM variable has to be transformed into the
  29 corresponding representation as a scm_bits_t variable y by using the
  30 SCM_UNPACK macro.  After this has been done, the type of the scheme object x
  31 can be derived from the content of the bits of the scm_bits_t value y, as is
  32 described in -->data-rep.  A valid bit encoding of a scheme value as a
  33 scm_bits_t variable can be transformed into the corresponding SCM value by
  34 using the SCM_PACK macro.
  35
  36 - scm_bits_t SCM_UNPACK (SCM x):  Transforms the SCM value x into it's
  37 representation as an integral type.  Only after applying SCM_UNPACK it is
  38 possible to access the bits and contents of the SCM value.
  39
  40 - SCM SCM_PACK (scm_bits_t x):  Takes a valid integral representation of a
  41 scheme object and transforms it into its representation as a SCM value.
  42
  43
  44 Immediate objects
  45 =================
  46
  47 A scheme object may either be an immediate, i. e. carrying all necessary
  48 information by itself, or it may contain a reference to a 'cell' with
  49 additional information on the heap.  While the fact, whether an object is an
  50 immediate or not should be irrelevant for user code, within guile's own code
  51 the distinction is sometimes of importance.  Thus, the following low level
  52 macro is provided:
  53
  54 - int SCM_IMP (SCM x):  A scheme object is an immediate if it fullfills the
  55 SCM_IMP predicate, otherwise it holds an encoded reference to a heap cell.
  56 The result of the predicate is delivered as a C style boolean value.  User
  57 code and code that extends guile should normally not be required to use this
  58 macro.
  59
  60 Summary:
  61 * For a scheme object x of unknown type, check first with SCM_IMP (x) if it is
  62 an immediate object.  If so, all of the type and value information can be
  63 determined from the scm_bits_t value that is delivered by SCM_UNPACK (x).
  64
  65
  66 Non immediate objects
  67 =====================
  68
  69 - (scm_t_cell *) SCM2PTR (SCM x)         (FIXME:: this name should be changed)
  70 - SCM PTR2SCM (scm_t_cell * x)           (FIXME:: this name should be changed)
  71
  72 A scheme object of type SCM that does not fullfill the SCM_IMP predicate holds
  73 an encoded reference to a heap cell.  This reference can be decoded to a C
  74 pointer to a heap cell using the SCM2PTR macro.  The encoding of a pointer to
  75 a heap cell into a SCM value is done using the PTR2SCM macro.
  76
  77 Note that it is also possible to transform a non immediate SCM value by using
  78 SCM_UNPACK into a scm_bits_t variable.  Hower, the result of SCM_UNPACK may
  79 not be used as a pointer to a scm_t_cell:  Only SCM2PTR is guaranteed to
  80 transform a SCM object into a valid pointer to a heap cell.  Also, it is not
  81 allowed to apply PTR2SCM to anything that is not a valid pointer to a heap
  82 cell.
  83
  84 Summary:
  85 * Only use SCM2PTR for SCM values for which SCM_IMP is false!
  86 * Don't use '(scm_t_cell*) SCM_UNPACK (x)'!  Use 'SCM2PTR (x)' instead!
  87 * Don't use PTR2SCM for anything but a cell pointer!
  88
  89
  90 Heap Cell Type Information
  91 ==========================
  92
  93 Heap cells contain a number of entries, each of which is either a scheme
  94 object of type SCM or a raw C value of type scm_bits_t.  Which of the cell
  95 entries contain scheme objects and which contain raw C values is determined by
  96 the first entry of the cell, which holds the cell type information.
  97
  98 - scm_bits_t SCM_CELL_TYPE (SCM x):  For a non immediate scheme object x,
  99 deliver the content of the first entry of the heap cell referenced by x.  This
 100 value holds the information about the cell type as described in -->data-rep.
 101
 102 - void SCM_SET_CELL_TYPE (SCM x, scm_bits_t t):  For a non immediate scheme
 103 object x, write the value t into the first entry of the heap cell referenced
 104 by x.  The value t must hold a valid cell type as described in -->data-rep.
 105
 106
 107 Accessing Cell Entries
 108 ======================
 109
 110 For a non immediate scheme object x, the object type can be determined by
 111 reading the cell type entry using the SCM_CELL_TYPE macro.  For the different
 112 types of cells it is known which cell entry holds scheme objects and which cell
 113 entry holds raw C data.  To access the different cell entries appropriately,
 114 the following macros are provided:
 115
 116 - scm_bits_t SCM_CELL_WORD (SCM x, unsigned int n):  Deliver the cell entry n
 117 of the heap cell referenced by the non immediate scheme object x as raw data.
 118 It is illegal, to access cell entries that hold scheme objects by using these
 119 macros.  For convenience, the following macros are also provided:
 120   SCM_CELL_WORD_0 (x)  -->  SCM_CELL_WORD (x, 0)
 121   SCM_CELL_WORD_1 (x)  -->  SCM_CELL_WORD (x, 1)
 122   ...
 123   SCM_CELL_WORD_n (x)  -->  SCM_CELL_WORD (x, n)
 124
 125 - SCM SCM_CELL_OBJECT (SCM x, unsigned int n):  Deliver the cell entry n of
 126 the heap cell referenced by the non immediate scheme object x as a scheme
 127 object.  It is illegal, to access cell entries that do not hold scheme objects
 128 by using these macros.  For convenience, the following macros are also
 129 provided:
 130   SCM_CELL_OBJECT_0 (x)  -->  SCM_CELL_OBJECT (x, 0)
 131   SCM_CELL_OBJECT_1 (x)  -->  SCM_CELL_OBJECT (x, 1)
 132   ...
 133   SCM_CELL_OBJECT_n (x)  -->  SCM_CELL_OBJECT (x, n)
 134
 135 - void SCM_SET_CELL_WORD (SCM x, unsigned int n, scm_bits_t w):  Write the raw
 136 C value w into entry number n of the heap cell referenced by the non immediate
 137 scheme value x.  Values that are written into cells this way may only be read
 138 from the cells using the SCM_CELL_WORD macros or, in case cell entry 0 is
 139 written, using the SCM_CELL_TYPE macro.  For the special case of cell entry 0
 140 it has to be made sure that w contains a cell type information (see
 141 -->data-rep) which does not describe a scheme object.  For convenience, the
 142 following macros are also provided:
 143   SCM_SET_CELL_WORD_0 (x, w)  -->  SCM_SET_CELL_WORD (x, 0, w)
 144   SCM_SET_CELL_WORD_1 (x, w)  -->  SCM_SET_CELL_WORD (x, 1, w)
 145   ...
 146   SCM_SET_CELL_WORD_n (x, w)  -->  SCM_SET_CELL_WORD (x, n, w)
 147
 148 - void SCM_SET_CELL_OBJECT (SCM x, unsigned int n, SCM o):  Write the scheme
 149 object o into entry number n of the heap cell referenced by the non immediate
 150 scheme value x.  Values that are written into cells this way may only be read
 151 from the cells using the SCM_CELL_OBJECT macros or, in case cell entry 0 is
 152 written, using the SCM_CELL_TYPE macro.  For the special case of cell entry 0
 153 the writing of a scheme object into this cell is only allowed, if the cell
 154 forms a scheme pair.  For convenience, the following macros are also provided:
 155   SCM_SET_CELL_OBJECT_0 (x, o)  -->  SCM_SET_CELL_OBJECT (x, 0, o)
 156   SCM_SET_CELL_OBJECT_1 (x, o)  -->  SCM_SET_CELL_OBJECT (x, 1, o)
 157   ...
 158   SCM_SET_CELL_OBJECT_n (x, o)  -->  SCM_SET_CELL_OBJECT (x, n, o)
 159
 160 Summary:
 161 * For a non immediate scheme object x of unknown type, get the type
 162   information by using SCM_CELL_TYPE (x).
 163 * As soon as the cell type information is available, only use the appropriate
 164   access methods to read and write data to the different cell entries.
 165
 166
 167 Basic Rules for Accessing Cell Entries
 168 ======================================
 169
 170 For each cell type it is generally up to the implementation of that type which
 171 of the corresponding cell entries hold scheme objects and which hold raw C
 172 values.  However, there is one basic rules that has to be followed:  Scheme
 173 pairs consist of exactly two cell entries, which both contain scheme objects.
 174 Further, a cell which contains a scheme object in it first entry has to be a
 175 scheme pair.  In other words, it is not allowed to store a scheme object in
 176 the first cell entry and a non scheme object in the second cell entry.
 177
 178 Fixme:shouldn't this rather be SCM_PAIRP / SCM_PAIR_P ?
 179 - int SCM_CONSP (SCM x):  Determine, whether the scheme object x is a scheme
 180 pair, i. e. whether x references a heap cell consisting of exactly two
 181 entries, where both entries contain a scheme object.  In this case, both
 182 entries will have to be accessed using the SCM_CELL_OBJECT macros.  On the
 183 contrary, if the SCM_CONSP predicate is not fulfilled, the first entry of the
 184 scheme cell is guaranteed not to be a scheme value and thus the first cell
 185 entry must be accessed using the SCM_CELL_WORD_0 macro.