For all but the most trivial applications, you will probably want to allow some representation of your domain objects to exist on the Scheme level. This is where foreign objects come in, and with them issues of lifetime management and garbage collection.
To get more concrete about this, let’s look again at the example we gave earlier of how application users can use Guile to build higher-level functions from the primitives that Dia itself provides.
(define (change-squares'-fill-pattern new-pattern) (for-each-shape current-page (lambda (shape) (if (square? shape) (change-fill-pattern shape new-pattern)))))
Consider what is stored here in the variable shape
. For each
shape on the current page, the for-each-shape
primitive calls
(lambda (shape) …)
with an argument representing that
shape. Question is: how is that argument represented on the Scheme
level? The issues are as follows.
square?
and change-fill-pattern
primitives. In
other words, a primitive like square?
has somehow to be able to
turn the value that it receives back into something that points to the
underlying C structure describing a shape.
shape
in a global variable, but then that shape is deleted (in a
way that the Scheme code is not aware of), and later on some other
Scheme code uses that global variable again in a call to, say,
square?
?
shape
argument passes
transiently in and out of the Scheme world, it would be quite wrong the
delete the underlying C shape just because the Scheme code has
finished evaluation. How do we avoid this happening?
One resolution of these issues is for the Scheme-level representation of
a shape to be a new, Scheme-specific C structure wrapped up as a foreign
object. The foreign object is what is passed into and out of Scheme
code, and the Scheme-specific C structure inside the foreign object
points to Dia’s underlying C structure so that the code for primitives
like square?
can get at it.
To cope with an underlying shape being deleted while Scheme code is still holding onto a Scheme shape value, the underlying C structure should have a new field that points to the Scheme-specific foreign object. When a shape is deleted, the relevant code chains through to the Scheme-specific structure and sets its pointer back to the underlying structure to NULL. Thus the foreign object value for the shape continues to exist, but any primitive code that tries to use it will detect that the underlying shape has been deleted because the underlying structure pointer is NULL.
So, to summarize the steps involved in this resolution of the problem
(and assuming that the underlying C structure for a shape is
struct dia_shape
):
struct dia_guile_shape { struct dia_shape * c_shape; /* NULL => deleted */ }
struct dia_shape
that points to its struct
dia_guile_shape
if it has one —
struct dia_shape { ... struct dia_guile_shape * guile_shape; }
— so that C code can set guile_shape->c_shape
to NULL when the
underlying shape is deleted.
struct dia_guile_shape
as a foreign object type.
c_shape
field when decoding it, to find out whether the
underlying C shape is still there.
As far as memory management is concerned, the foreign object values and their Scheme-specific structures are under the control of the garbage collector, whereas the underlying C structures are explicitly managed in exactly the same way that Dia managed them before we thought of adding Guile.
When the garbage collector decides to free a shape foreign object value,
it calls the finalizer function that was specified when defining
the shape foreign object type. To maintain the correctness of the
guile_shape
field in the underlying C structure, this function
should chain through to the underlying C structure (if it still exists)
and set its guile_shape
field to NULL.
For full documentation on defining and using foreign object types, see Defining New Foreign Object Types.