diff options
Diffstat (limited to 'doc/ref/api.txt')
-rw-r--r-- | doc/ref/api.txt | 185 |
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. |