[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
5.5.1 Describing a New Type
To define a new type, the programmer must write four functions to manage instances of the type:
mark
Guile will apply this function to each instance of the new type it encounters during garbage collection. This function is responsible for telling the collector about any other
SCM
values that the object has stored. The default smob mark function does nothing. See section Garbage Collecting Smobs, for more details.free
Guile will apply this function to each instance of the new type that is to be deallocated. The function should release all resources held by the object. This is analogous to the Java finalization method– it is invoked at an unspecified time (when garbage collection occurs) after the object is dead. The default free function frees the smob data (if the size of the struct passed to
scm_make_smob_type
is non-zero) usingscm_gc_free
. See section Garbage Collecting Smobs, for more details.This function operates while the heap is in an inconsistent state and must therefore be careful. See section Smobs, for details about what this function is allowed to do.
print
Guile will apply this function to each instance of the new type to print the value, as for
display
orwrite
. The default print function prints#<NAME ADDRESS>
whereNAME
is the first argument passed toscm_make_smob_type
.equalp
If Scheme code asks the
equal?
function to compare two instances of the same smob type, Guile calls this function. It should returnSCM_BOOL_T
if a and b should be consideredequal?
, orSCM_BOOL_F
otherwise. Ifequalp
isNULL
,equal?
will assume that two instances of this type are neverequal?
unless they areeq?
.
To actually register the new smob type, call scm_make_smob_type
.
It returns a value of type scm_t_bits
which identifies the new
smob type.
The four special functions described above are registered by calling
one of scm_set_smob_mark
, scm_set_smob_free
,
scm_set_smob_print
, or scm_set_smob_equalp
, as
appropriate. Each function is intended to be used at most once per
type, and the call should be placed immediately following the call to
scm_make_smob_type
.
There can only be at most 256 different smob types in the system. Instead of registering a huge number of smob types (for example, one for each relevant C struct in your application), it is sometimes better to register just one and implement a second layer of type dispatching on top of it. This second layer might use the 16 extra bits to extend its type, for example.
Here is how one might declare and register a new type representing eight-bit gray-scale images:
#include <libguile.h> struct image { int width, height; char *pixels; /* The name of this image */ SCM name; /* A function to call when this image is modified, e.g., to update the screen, or SCM_BOOL_F if no action necessary */ SCM update_func; }; static scm_t_bits image_tag; void init_image_type (void) { image_tag = scm_make_smob_type ("image", sizeof (struct image)); scm_set_smob_mark (image_tag, mark_image); scm_set_smob_free (image_tag, free_image); scm_set_smob_print (image_tag, print_image); }
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on April 20, 2013 using texi2html 5.0.