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