1077 |
the @code{SCM} type with utility functions and macros. |
the @code{SCM} type with utility functions and macros. |
1078 |
|
|
1079 |
@item |
@item |
1080 |
@code{scm_bits_t} is an integral data type that is guaranteed to be |
@code{scm_t_bits} is an integral data type that is guaranteed to be |
1081 |
large enough to hold all information that is required to represent any |
large enough to hold all information that is required to represent any |
1082 |
Scheme object. While this data type is mostly used to implement Guile's |
Scheme object. While this data type is mostly used to implement Guile's |
1083 |
internals, the use of this type is also necessary to write certain kinds |
internals, the use of this type is also necessary to write certain kinds |
1085 |
@end itemize |
@end itemize |
1086 |
|
|
1087 |
@menu |
@menu |
1088 |
* Relationship between SCM and scm_bits_t:: |
* Relationship between SCM and scm_t_bits:: |
1089 |
* Immediate objects:: |
* Immediate objects:: |
1090 |
* Non-immediate objects:: |
* Non-immediate objects:: |
1091 |
* Heap Cell Type Information:: |
* Heap Cell Type Information:: |
1094 |
@end menu |
@end menu |
1095 |
|
|
1096 |
|
|
1097 |
@node Relationship between SCM and scm_bits_t |
@node Relationship between SCM and scm_t_bits |
1098 |
@subsubsection Relationship between @code{SCM} and @code{scm_bits_t} |
@subsubsection Relationship between @code{SCM} and @code{scm_t_bits} |
1099 |
|
|
1100 |
A variable of type @code{SCM} is guaranteed to hold a valid Scheme |
A variable of type @code{SCM} is guaranteed to hold a valid Scheme |
1101 |
object. A variable of type @code{scm_bits_t}, on the other hand, may |
object. A variable of type @code{scm_t_bits}, on the other hand, may |
1102 |
hold a representation of a @code{SCM} value as a C integral type, but |
hold a representation of a @code{SCM} value as a C integral type, but |
1103 |
may also hold any C value, even if it does not correspond to a valid |
may also hold any C value, even if it does not correspond to a valid |
1104 |
Scheme object. |
Scheme object. |
1107 |
information is stored in a form that is not directly usable. To be able |
information is stored in a form that is not directly usable. To be able |
1108 |
to work on the type encoding of the scheme value, the @code{SCM} |
to work on the type encoding of the scheme value, the @code{SCM} |
1109 |
variable has to be transformed into the corresponding representation as |
variable has to be transformed into the corresponding representation as |
1110 |
a @code{scm_bits_t} variable @var{y} by using the @code{SCM_UNPACK} |
a @code{scm_t_bits} variable @var{y} by using the @code{SCM_UNPACK} |
1111 |
macro. Once this has been done, the type of the scheme object @var{x} |
macro. Once this has been done, the type of the scheme object @var{x} |
1112 |
can be derived from the content of the bits of the @code{scm_bits_t} |
can be derived from the content of the bits of the @code{scm_t_bits} |
1113 |
value @var{y}, in the way illustrated by the example earlier in this |
value @var{y}, in the way illustrated by the example earlier in this |
1114 |
chapter (@pxref{Cheaper Pairs}). Conversely, a valid bit encoding of a |
chapter (@pxref{Cheaper Pairs}). Conversely, a valid bit encoding of a |
1115 |
Scheme value as a @code{scm_bits_t} variable can be transformed into the |
Scheme value as a @code{scm_t_bits} variable can be transformed into the |
1116 |
corresponding @code{SCM} value using the @code{SCM_PACK} macro. |
corresponding @code{SCM} value using the @code{SCM_PACK} macro. |
1117 |
|
|
1118 |
@deftypefn Macro scm_bits_t SCM_UNPACK (SCM @var{x}) |
@deftypefn Macro scm_t_bits SCM_UNPACK (SCM @var{x}) |
1119 |
Transforms the @code{SCM} value @var{x} into its representation as an |
Transforms the @code{SCM} value @var{x} into its representation as an |
1120 |
integral type. Only after applying @code{SCM_UNPACK} it is possible to |
integral type. Only after applying @code{SCM_UNPACK} it is possible to |
1121 |
access the bits and contents of the @code{SCM} value. |
access the bits and contents of the @code{SCM} value. |
1122 |
@end deftypefn |
@end deftypefn |
1123 |
|
|
1124 |
@deftypefn Macro SCM SCM_PACK (scm_bits_t @var{x}) |
@deftypefn Macro SCM SCM_PACK (scm_t_bits @var{x}) |
1125 |
Takes a valid integral representation of a Scheme object and transforms |
Takes a valid integral representation of a Scheme object and transforms |
1126 |
it into its representation as a @code{SCM} value. |
it into its representation as a @code{SCM} value. |
1127 |
@end deftypefn |
@end deftypefn |
1153 |
with @code{SCM_IMP (@var{x})} if it is an immediate object. |
with @code{SCM_IMP (@var{x})} if it is an immediate object. |
1154 |
@item |
@item |
1155 |
If so, all of the type and value information can be determined from the |
If so, all of the type and value information can be determined from the |
1156 |
@code{scm_bits_t} value that is delivered by @code{SCM_UNPACK |
@code{scm_t_bits} value that is delivered by @code{SCM_UNPACK |
1157 |
(@var{x})}. |
(@var{x})}. |
1158 |
@end itemize |
@end itemize |
1159 |
|
|
1180 |
@end deftypefn |
@end deftypefn |
1181 |
|
|
1182 |
Note that it is also possible to transform a non-immediate @code{SCM} |
Note that it is also possible to transform a non-immediate @code{SCM} |
1183 |
value by using @code{SCM_UNPACK} into a @code{scm_bits_t} variable. |
value by using @code{SCM_UNPACK} into a @code{scm_t_bits} variable. |
1184 |
However, the result of @code{SCM_UNPACK} may not be used as a pointer to |
However, the result of @code{SCM_UNPACK} may not be used as a pointer to |
1185 |
a @code{scm_t_cell}: only @code{SCM2PTR} is guaranteed to transform a |
a @code{scm_t_cell}: only @code{SCM2PTR} is guaranteed to transform a |
1186 |
@code{SCM} object into a valid pointer to a heap cell. Also, it is not |
@code{SCM} object into a valid pointer to a heap cell. Also, it is not |
1205 |
@subsubsection Heap Cell Type Information |
@subsubsection Heap Cell Type Information |
1206 |
|
|
1207 |
Heap cells contain a number of entries, each of which is either a scheme |
Heap cells contain a number of entries, each of which is either a scheme |
1208 |
object of type @code{SCM} or a raw C value of type @code{scm_bits_t}. |
object of type @code{SCM} or a raw C value of type @code{scm_t_bits}. |
1209 |
Which of the cell entries contain Scheme objects and which contain raw C |
Which of the cell entries contain Scheme objects and which contain raw C |
1210 |
values is determined by the first entry of the cell, which holds the |
values is determined by the first entry of the cell, which holds the |
1211 |
cell type information. |
cell type information. |
1212 |
|
|
1213 |
@deftypefn Macro scm_bits_t SCM_CELL_TYPE (SCM @var{x}) |
@deftypefn Macro scm_t_bits SCM_CELL_TYPE (SCM @var{x}) |
1214 |
For a non-immediate Scheme object @var{x}, deliver the content of the |
For a non-immediate Scheme object @var{x}, deliver the content of the |
1215 |
first entry of the heap cell referenced by @var{x}. This value holds |
first entry of the heap cell referenced by @var{x}. This value holds |
1216 |
the information about the cell type. |
the information about the cell type. |
1217 |
@end deftypefn |
@end deftypefn |
1218 |
|
|
1219 |
@deftypefn Macro void SCM_SET_CELL_TYPE (SCM @var{x}, scm_bits_t @var{t}) |
@deftypefn Macro void SCM_SET_CELL_TYPE (SCM @var{x}, scm_t_bits @var{t}) |
1220 |
For a non-immediate Scheme object @var{x}, write the value @var{t} into |
For a non-immediate Scheme object @var{x}, write the value @var{t} into |
1221 |
the first entry of the heap cell referenced by @var{x}. The value |
the first entry of the heap cell referenced by @var{x}. The value |
1222 |
@var{t} must hold a valid cell type. |
@var{t} must hold a valid cell type. |
1233 |
the different cell entries appropriately, the following macros are |
the different cell entries appropriately, the following macros are |
1234 |
provided. |
provided. |
1235 |
|
|
1236 |
@deftypefn Macro scm_bits_t SCM_CELL_WORD (SCM @var{x}, unsigned int @var{n}) |
@deftypefn Macro scm_t_bits SCM_CELL_WORD (SCM @var{x}, unsigned int @var{n}) |
1237 |
Deliver the cell entry @var{n} of the heap cell referenced by the |
Deliver the cell entry @var{n} of the heap cell referenced by the |
1238 |
non-immediate Scheme object @var{x} as raw data. It is illegal, to |
non-immediate Scheme object @var{x} as raw data. It is illegal, to |
1239 |
access cell entries that hold Scheme objects by using these macros. For |
access cell entries that hold Scheme objects by using these macros. For |
1268 |
@end itemize |
@end itemize |
1269 |
@end deftypefn |
@end deftypefn |
1270 |
|
|
1271 |
@deftypefn Macro void SCM_SET_CELL_WORD (SCM @var{x}, unsigned int @var{n}, scm_bits_t @var{w}) |
@deftypefn Macro void SCM_SET_CELL_WORD (SCM @var{x}, unsigned int @var{n}, scm_t_bits @var{w}) |
1272 |
Write the raw C value @var{w} into entry number @var{n} of the heap cell |
Write the raw C value @var{w} into entry number @var{n} of the heap cell |
1273 |
referenced by the non-immediate Scheme value @var{x}. Values that are |
referenced by the non-immediate Scheme value @var{x}. Values that are |
1274 |
written into cells this way may only be read from the cells using the |
written into cells this way may only be read from the cells using the |
1432 |
|
|
1433 |
To actually register the new smob type, call @code{scm_make_smob_type}: |
To actually register the new smob type, call @code{scm_make_smob_type}: |
1434 |
|
|
1435 |
@deftypefun scm_bits_t scm_make_smob_type (const char *name, size_t size) |
@deftypefun scm_t_bits scm_make_smob_type (const char *name, size_t size) |
1436 |
This function implements the standard way of adding a new smob type, |
This function implements the standard way of adding a new smob type, |
1437 |
named @var{name}, with instance size @var{size}, to the system. The |
named @var{name}, with instance size @var{size}, to the system. The |
1438 |
return value is a tag that is used in creating instances of the type. |
return value is a tag that is used in creating instances of the type. |
1451 |
only zero or one time per type, and the call should be placed |
only zero or one time per type, and the call should be placed |
1452 |
immediately following the call to @code{scm_make_smob_type}. |
immediately following the call to @code{scm_make_smob_type}. |
1453 |
|
|
1454 |
@deftypefun void scm_set_smob_mark (scm_bits_t tc, SCM (*mark) (SCM)) |
@deftypefun void scm_set_smob_mark (scm_t_bits tc, SCM (*mark) (SCM)) |
1455 |
This function sets the smob marking procedure for the smob type specified by |
This function sets the smob marking procedure for the smob type specified by |
1456 |
the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}. |
the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}. |
1457 |
@end deftypefun |
@end deftypefun |
1458 |
|
|
1459 |
@deftypefun void scm_set_smob_free (scm_bits_t tc, size_t (*free) (SCM)) |
@deftypefun void scm_set_smob_free (scm_t_bits tc, size_t (*free) (SCM)) |
1460 |
This function sets the smob freeing procedure for the smob type specified by |
This function sets the smob freeing procedure for the smob type specified by |
1461 |
the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}. |
the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}. |
1462 |
@end deftypefun |
@end deftypefun |
1463 |
|
|
1464 |
@deftypefun void scm_set_smob_print (scm_bits_t tc, int (*print) (SCM, SCM, scm_print_state*)) |
@deftypefun void scm_set_smob_print (scm_t_bits tc, int (*print) (SCM, SCM, scm_print_state*)) |
1465 |
This function sets the smob printing procedure for the smob type specified by |
This function sets the smob printing procedure for the smob type specified by |
1466 |
the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}. |
the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}. |
1467 |
@end deftypefun |
@end deftypefun |
1468 |
|
|
1469 |
@deftypefun void scm_set_smob_equalp (scm_bits_t tc, SCM (*equalp) (SCM, SCM)) |
@deftypefun void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM, SCM)) |
1470 |
This function sets the smob equality-testing predicate for the smob type specified by |
This function sets the smob equality-testing predicate for the smob type specified by |
1471 |
the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}. |
the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}. |
1472 |
@end deftypefun |
@end deftypefun |
1500 |
@example |
@example |
1501 |
#include <libguile.h> |
#include <libguile.h> |
1502 |
|
|
1503 |
static scm_bits_t image_tag; |
static scm_t_bits image_tag; |
1504 |
|
|
1505 |
void |
void |
1506 |
init_image_type (void) |
init_image_type (void) |
1529 |
@code{SCM_NEWSMOB3} variants will allocate double cells and thus use |
@code{SCM_NEWSMOB3} variants will allocate double cells and thus use |
1530 |
twice as much memory as smobs created by @code{SCM_NEWSMOB}.} |
twice as much memory as smobs created by @code{SCM_NEWSMOB}.} |
1531 |
|
|
1532 |
@deftypefn Macro void SCM_NEWSMOB(SCM value, scm_bits_t tag, void *data) |
@deftypefn Macro void SCM_NEWSMOB(SCM value, scm_t_bits tag, void *data) |
1533 |
@deftypefnx Macro void SCM_NEWSMOB2(SCM value, scm_bits_t tag, void *data1, void *data2) |
@deftypefnx Macro void SCM_NEWSMOB2(SCM value, scm_t_bits tag, void *data1, void *data2) |
1534 |
@deftypefnx Macro void SCM_NEWSMOB3(SCM value, scm_bits_t tag, void *data1, void *data2, void *data3) |
@deftypefnx Macro void SCM_NEWSMOB3(SCM value, scm_t_bits tag, void *data1, void *data2, void *data3) |
1535 |
Make @var{value} contain a smob instance of the type with tag @var{tag} |
Make @var{value} contain a smob instance of the type with tag @var{tag} |
1536 |
and smob data @var{data} (or @var{data1}, @var{data2}, and @var{data3}). |
and smob data @var{data} (or @var{data1}, @var{data2}, and @var{data3}). |
1537 |
@var{value} must be previously declared as C type @code{SCM}. |
@var{value} must be previously declared as C type @code{SCM}. |
1541 |
create a smob instance and return it, there is also a slightly specialized |
create a smob instance and return it, there is also a slightly specialized |
1542 |
macro for this situation: |
macro for this situation: |
1543 |
|
|
1544 |
@deftypefn Macro fn_returns SCM_RETURN_NEWSMOB(scm_bits_t tag, void *data) |
@deftypefn Macro fn_returns SCM_RETURN_NEWSMOB(scm_t_bits tag, void *data) |
1545 |
@deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB2(scm_bits_t tag, void *data1, void *data2) |
@deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB2(scm_t_bits tag, void *data1, void *data2) |
1546 |
@deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB3(scm_bits_t tag, void *data1, void *data2, void *data3) |
@deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB3(scm_t_bits tag, void *data1, void *data2, void *data3) |
1547 |
This macro expands to a block of code that creates a smob instance of |
This macro expands to a block of code that creates a smob instance of |
1548 |
the type with tag @var{tag} and smob data @var{data} (or @var{data1}, |
the type with tag @var{tag} and smob data @var{data} (or @var{data1}, |
1549 |
@var{data2}, and @var{data3}), and returns that @code{SCM} value. It |
@var{data2}, and @var{data3}), and causes the surrounding function to |
1550 |
should be the last piece of code in a block. |
return that @code{SCM} value. It should be the last piece of code in |
1551 |
|
a block. |
1552 |
@end deftypefn |
@end deftypefn |
1553 |
|
|
1554 |
Guile provides the following functions for managing memory, which are |
Guile provides the following functions for managing memory, which are |
1943 |
#include <stdlib.h> |
#include <stdlib.h> |
1944 |
#include <libguile.h> |
#include <libguile.h> |
1945 |
|
|
1946 |
static scm_bits_t image_tag; |
static scm_t_bits image_tag; |
1947 |
|
|
1948 |
struct image @{ |
struct image @{ |
1949 |
int width, height; |
int width, height; |