396 |
the @code{SCM} value. This may be significant when traversing lists, a |
the @code{SCM} value. This may be significant when traversing lists, a |
397 |
common activity in a Scheme system. |
common activity in a Scheme system. |
398 |
|
|
399 |
Again, most real Scheme systems use a slighty different implementation; |
Again, most real Scheme systems use a slightly different implementation; |
400 |
for example, if GET_PAIR subtracts off the low bits of @code{x}, instead |
for example, if GET_PAIR subtracts off the low bits of @code{x}, instead |
401 |
of masking them off, the optimizer will often be able to combine that |
of masking them off, the optimizer will often be able to combine that |
402 |
subtraction with the addition of the offset of the structure member we |
subtraction with the addition of the offset of the structure member we |
564 |
includes small integers, characters, boolean values, the empty list, the |
includes small integers, characters, boolean values, the empty list, the |
565 |
mysterious end-of-file object, and some others. |
mysterious end-of-file object, and some others. |
566 |
|
|
567 |
The remaining types are called, not suprisingly, @dfn{non-immediates}. |
The remaining types are called, not surprisingly, @dfn{non-immediates}. |
568 |
They include pairs, procedures, strings, vectors, and all other data |
They include pairs, procedures, strings, vectors, and all other data |
569 |
types in Guile. |
types in Guile. |
570 |
|
|
816 |
contents. |
contents. |
817 |
@end deftypefun |
@end deftypefun |
818 |
|
|
819 |
The macros below perform no typechecking. The results are undefined if |
The macros below perform no type checking. The results are undefined if |
820 |
@var{cell} is an immediate. However, since all non-immediate Guile |
@var{cell} is an immediate. However, since all non-immediate Guile |
821 |
objects are constructed from cells, and these macros simply return the |
objects are constructed from cells, and these macros simply return the |
822 |
first element of a cell, they actually can be useful on datatypes other |
first element of a cell, they actually can be useful on datatypes other |
968 |
A subr is a pointer to a C function, packaged up as a Scheme object to |
A subr is a pointer to a C function, packaged up as a Scheme object to |
969 |
make it callable by Scheme code. In addition to the function pointer, |
make it callable by Scheme code. In addition to the function pointer, |
970 |
the subr also contains a pointer to the name of the function, and |
the subr also contains a pointer to the name of the function, and |
971 |
information about the number of arguments accepted by the C fuction, for |
information about the number of arguments accepted by the C function, for |
972 |
the sake of error checking. |
the sake of error checking. |
973 |
|
|
974 |
There is no single type predicate macro that recognizes subrs, as |
There is no single type predicate macro that recognizes subrs, as |
1161 |
@node Non-immediate objects |
@node Non-immediate objects |
1162 |
@subsubsection Non-immediate objects |
@subsubsection Non-immediate objects |
1163 |
|
|
1164 |
A Scheme object of type @code{SCM} that does not fullfill the |
A Scheme object of type @code{SCM} that does not fulfill the |
1165 |
@code{SCM_IMP} predicate holds an encoded reference to a heap cell. |
@code{SCM_IMP} predicate holds an encoded reference to a heap cell. |
1166 |
This reference can be decoded to a C pointer to a heap cell using the |
This reference can be decoded to a C pointer to a heap cell using the |
1167 |
@code{SCM2PTR} macro. The encoding of a pointer to a heap cell into a |
@code{SCM2PTR} macro. The encoding of a pointer to a heap cell into a |
1377 |
@menu |
@menu |
1378 |
* Describing a New Type:: |
* Describing a New Type:: |
1379 |
* Creating Instances:: |
* Creating Instances:: |
1380 |
* Typechecking:: |
* Type checking:: |
1381 |
* Garbage Collecting Smobs:: |
* Garbage Collecting Smobs:: |
1382 |
* A Common Mistake In Allocating Smobs:: |
* A Common Mistake In Allocating Smobs:: |
1383 |
* Garbage Collecting Simple Smobs:: |
* Garbage Collecting Simple Smobs:: |
1402 |
Guile will apply this function to each instance of the new type it could |
Guile will apply this function to each instance of the new type it could |
1403 |
not find any live pointers to. The function should release all |
not find any live pointers to. The function should release all |
1404 |
resources held by the object and return the number of bytes released. |
resources held by the object and return the number of bytes released. |
1405 |
This is analagous to the Java finalization method-- it is invoked at an |
This is analogous to the Java finalization method-- it is invoked at an |
1406 |
unspecified time (when garbage collection occurs) after the object is |
unspecified time (when garbage collection occurs) after the object is |
1407 |
dead. The default free function frees the smob data (if the size of the |
dead. The default free function frees the smob data (if the size of the |
1408 |
struct passed to @code{scm_make_smob_type} is non-zero) using |
struct passed to @code{scm_make_smob_type} is non-zero) using |
1488 |
to add a new smob type named @var{name}, with instance size @var{size} to the system. |
to add a new smob type named @var{name}, with instance size @var{size} to the system. |
1489 |
It also registers the @var{mark}, @var{free}, @var{print}, @var{equalp} smob |
It also registers the @var{mark}, @var{free}, @var{print}, @var{equalp} smob |
1490 |
special functions for that new type. Any of these parameters can be @code{NULL} |
special functions for that new type. Any of these parameters can be @code{NULL} |
1491 |
to have that special function use the default behaviour for guile. |
to have that special function use the default behavior for guile. |
1492 |
The return value is a tag that is used in creating instances of the type. If @var{size} |
The return value is a tag that is used in creating instances of the type. If @var{size} |
1493 |
is 0, then no memory will be allocated when instances of the smob are created, and |
is 0, then no memory will be allocated when instances of the smob are created, and |
1494 |
nothing will be freed by the default free function. |
nothing will be freed by the default free function. |
1495 |
@end deftypefun |
@end deftypefun |
1496 |
|
|
1497 |
For example, here is how one might declare and register a new type |
For example, here is how one might declare and register a new type |
1498 |
representing eight-bit grayscale images: |
representing eight-bit gray-scale images: |
1499 |
|
|
1500 |
@example |
@example |
1501 |
#include <libguile.h> |
#include <libguile.h> |
1635 |
@end example |
@end example |
1636 |
|
|
1637 |
|
|
1638 |
@node Typechecking |
@node Type checking |
1639 |
@subsection Typechecking |
@subsection Type checking |
1640 |
|
|
1641 |
Functions that operate on smobs should aggressively check the types of |
Functions that operate on smobs should aggressively check the types of |
1642 |
their arguments, to avoid misinterpreting some other datatype as a smob, |
their arguments, to avoid misinterpreting some other datatype as a smob, |