Added a first attempt for a description of the low level API.

doc/ChangeLog

@@ -1,3 +1,8 @@
+2000-03-22  Dirk Herrmann  <D.Herrmann@tu-bs.de>
+
+	* api.txt:  Added a first attempt for a description of the newly
+	designed low level API.
+
 Thu Jan 20 13:00:18 2000  Greg J. Badros  <gjb@cs.washington.edu>
 
 	* version.texi, stamp-vti: Removed -- these are auto-generated.

doc/api.txt

@@ -0,0 +1,185 @@
+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_cell *) SCM2PTR (SCM x)           (FIXME:: this name should be changed)
+- SCM PTR2SCM (scm_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_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_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 know 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.