(guile.info.gz) Describing a New Type
Info Catalog
(guile.info.gz) Defining New Types (Smobs)
(guile.info.gz) Creating Instances
18.3.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
non-immediate objects the object refers to. The default smob mark
function is to not mark any data. Garbage Collecting
Smobs, for more details.
`free'
Guile will apply this function to each instance of the new type it
could not find any live pointers to. The function should release
all resources held by the object and return the number of bytes
released. 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) using `scm_must_free' and
returns the size of that struct. Garbage Collecting
Smobs, for more details.
`print'
Guile will apply this function to each instance of the new type to
print the value, as for `display' or `write'. The function should
write a printed representation of EXP on PORT, in accordance with
the parameters in PSTATE. (For more information on print states,
see Port Data.) The default print function prints `#<NAME
ADDRESS>' where `NAME' is the first argument passed to
`scm_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 return
`SCM_BOOL_T' if A and B should be considered `equal?', or
`SCM_BOOL_F' otherwise. If `equalp' is `NULL', `equal?' will
assume that two instances of this type are never `equal?' unless
they are `eq?'.
To actually register the new smob type, call `scm_make_smob_type':
-- Function: scm_t_bits scm_make_smob_type (const char *name, size_t
size)
This function implements the standard way of adding a new smob
type, named NAME, with instance size SIZE, to the system. The
return value is a tag that is used in creating instances of the
type. If SIZE is 0, then no memory will be allocated when
instances of the smob are created, and nothing will be freed by
the default free function. Default values are provided for mark,
free, print, and, equalp, as described above. If you want to
customize any of these functions, the call to `scm_make_smob_type'
should be immediately followed by calls to one or several of
`scm_set_smob_mark', `scm_set_smob_free', `scm_set_smob_print',
and/or `scm_set_smob_equalp'.
Each of the below `scm_set_smob_XXX' functions registers a smob
special function for a given type. Each function is intended to be used
only zero or one time per type, and the call should be placed
immediately following the call to `scm_make_smob_type'.
-- Function: void scm_set_smob_mark (scm_t_bits tc, SCM (*mark) (SCM))
This function sets the smob marking procedure for the smob type
specified by the tag TC. TC is the tag returned by
`scm_make_smob_type'.
-- Function: void scm_set_smob_free (scm_t_bits tc, size_t (*free)
(SCM))
This function sets the smob freeing procedure for the smob type
specified by the tag TC. TC is the tag returned by
`scm_make_smob_type'.
-- Function: void scm_set_smob_print (scm_t_bits tc, int (*print)
(SCM, SCM, scm_print_state*))
This function sets the smob printing procedure for the smob type
specified by the tag TC. TC is the tag returned by
`scm_make_smob_type'.
-- Function: void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp)
(SCM, SCM))
This function sets the smob equality-testing predicate for the
smob type specified by the tag TC. TC is the tag returned by
`scm_make_smob_type'.
In versions 1.4 and earlier, there was another way of creating smob
types, using `scm_make_smob_type_mfpe'. This function is now
deprecated and will be removed in a future version of Guile. You should
use the mechanism described above for new code, and change old code not
to use deprecated features.
Instead of using `scm_make_smob_type' and calling each of the
individual `scm_set_smob_XXX' functions to register each special
function independently, you could use `scm_make_smob_type_mfpe' to
register all of the special functions at once as you create the smob
type
-- Function: long scm_make_smob_type_mfpe (const char *name, size_t
size, SCM (*mark) (SCM), size_t (*free) (SCM), int (*print)
(SCM, SCM, scm_print_state*), SCM (*equalp) (SCM, SCM))
This function invokes `scm_make_smob_type' on its first two
arguments to add a new smob type named NAME, with instance size
SIZE to the system. It also registers the MARK, FREE, PRINT,
EQUALP smob special functions for that new type. Any of these
parameters can be `NULL' to have that special function use the
default behavior for guile. The return value is a tag that is
used in creating instances of the type. If SIZE is 0, then no
memory will be allocated when instances of the smob are created,
and nothing will be freed by the default free function.
For example, here is how one might declare and register a new type
representing eight-bit gray-scale images:
#include <libguile.h>
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);
}
Info Catalog
(guile.info.gz) Defining New Types (Smobs)
(guile.info.gz) Creating Instances
automatically generated byinfo2html