summaryrefslogtreecommitdiff
path: root/doc/ref/api.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref/api.txt')
-rw-r--r--doc/ref/api.txt185
1 files changed, 0 insertions, 185 deletions
diff --git a/doc/ref/api.txt b/doc/ref/api.txt
deleted file mode 100644
index cc26b839f..000000000
--- a/doc/ref/api.txt
+++ /dev/null
@@ -1,185 +0,0 @@
-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.