6.8 Smobs

This chapter contains reference information related to defining and
working with smobs. See Defining New Types (Smobs) for a
tutorial-like introduction to smobs.

Function: scm_t_bitsscm_make_smob_type(const char *name, size_t size)

This function adds 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, the default free function will do nothing.

If size is not 0, the default free function will
deallocate the memory block pointed to by SCM_SMOB_DATA with
scm_gc_free. The what parameter in the call to
scm_gc_free will be name.

Default values are provided for the mark, free,
print, and equalp functions, as described in
Defining New Types (Smobs). 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.

This function sets the smob freeing procedure (sometimes referred to as
a finalizer) for the smob type specified by the tag
tc. tc is the tag returned by scm_make_smob_type.

The free procedure must deallocate all resources that are
directly associated with the smob instance obj. It must assume
that all SCM values that it references have already been freed
and are thus invalid.

It must also not call any libguile function or macro except
scm_gc_free, SCM_SMOB_FLAGS, SCM_SMOB_DATA,
SCM_SMOB_DATA_2, and SCM_SMOB_DATA_3.

The free procedure must return 0.

Note that defining a freeing procedure is not necessary if the resources
associated with obj consists only of memory allocated with
scm_gc_malloc or scm_gc_malloc_pointerless because this
memory is automatically reclaimed by the garbage collector when it is no
longer needed (see scm_gc_malloc).

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.

Defining a marking procedure may sometimes be unnecessary because large
parts of the process’ memory (with the exception of
scm_gc_malloc_pointerless regions, and malloc- or
scm_malloc-allocated memory) are scanned for live
pointers8.

The mark procedure must cause scm_gc_mark to be called
for every SCM value that is directly referenced by the smob
instance obj. One of these SCM values can be returned
from the procedure and Guile will call scm_gc_mark for it.
This can be used to avoid deep recursions for smob instances that form
a list.

It must not call any libguile function or macro except
scm_gc_mark, SCM_SMOB_FLAGS, SCM_SMOB_DATA,
SCM_SMOB_DATA_2, and SCM_SMOB_DATA_3.

Make a new smob of the type with tag tag and smob data data,
data2, and data3, as appropriate.

The tag is what has been returned by scm_make_smob_type.
The initial values data, data2, and data3 are of
type scm_t_bits; when you want to use them for SCM
values, these values need to be converted to a scm_t_bits first
by using SCM_UNPACK.

The flags of the smob instance start out as zero.

C Macro: scm_t_bitsSCM_SMOB_FLAGS(SCM obj)

Return the 16 extra bits of the smob obj. No meaning is
predefined for these bits, you can use them freely.

C Macro: scm_t_bitsSCM_SET_SMOB_FLAGS(SCM obj, scm_t_bits flags)

Set the 16 extra bits of the smob obj to flags. No
meaning is predefined for these bits, you can use them freely.

C Macro: scm_t_bitsSCM_SMOB_DATA(SCM obj)

C Macro: scm_t_bitsSCM_SMOB_DATA_2(SCM obj)

C Macro: scm_t_bitsSCM_SMOB_DATA_3(SCM obj)

Return the first (second, third) immediate word of the smob obj
as a scm_t_bits value. When the word contains a SCM
value, use SCM_SMOB_OBJECT (etc.) instead.

C Macro: voidSCM_SET_SMOB_DATA(SCM obj, scm_t_bits val)

C Macro: voidSCM_SET_SMOB_DATA_2(SCM obj, scm_t_bits val)

C Macro: voidSCM_SET_SMOB_DATA_3(SCM obj, scm_t_bits val)

Set the first (second, third) immediate word of the smob obj to
val. When the word should be set to a SCM value, use
SCM_SMOB_SET_OBJECT (etc.) instead.

C Macro: SCMSCM_SMOB_OBJECT(SCM obj)

C Macro: SCMSCM_SMOB_OBJECT_2(SCM obj)

C Macro: SCMSCM_SMOB_OBJECT_3(SCM obj)

Return the first (second, third) immediate word of the smob obj
as a SCM value. When the word contains a scm_t_bits
value, use SCM_SMOB_DATA (etc.) instead.

C Macro: voidSCM_SET_SMOB_OBJECT(SCM obj, SCM val)

C Macro: voidSCM_SET_SMOB_OBJECT_2(SCM obj, SCM val)

C Macro: voidSCM_SET_SMOB_OBJECT_3(SCM obj, SCM val)

Set the first (second, third) immediate word of the smob obj to
val. When the word should be set to a scm_t_bits value, use
SCM_SMOB_SET_DATA (etc.) instead.

C Macro: SCM *SCM_SMOB_OBJECT_LOC(SCM obj)

C Macro: SCM *SCM_SMOB_OBJECT_2_LOC(SCM obj)

C Macro: SCM *SCM_SMOB_OBJECT_3_LOC(SCM obj)

Return a pointer to the first (second, third) immediate word of the
smob obj. Note that this is a pointer to SCM. If you
need to work with scm_t_bits values, use SCM_PACK and
SCM_UNPACK, as appropriate.

Function: SCMscm_markcdr(SCM x)

Mark the references in the smob x, assuming that x’s first
data word contains an ordinary Scheme object, and x refers to no
other objects. This function simply returns x’s first data word.

Footnotes

Conversely, in Guile up to the 1.8 series, the marking
procedure was always required. The reason is that Guile’s GC would only
look for pointers in the memory area used for built-in types (the
cell heap), not in user-allocated or statically allocated memory.
This approach is often referred to as precise marking.