6.7 Foreign Objects

This chapter contains reference information related to defining and working with foreign objects. See Defining New Foreign Object Types, for a tutorial-like introduction to foreign objects.

C Type: scm_t_struct_finalize

This function type returns void and takes one SCM argument.

C Function: SCM scm_make_foreign_object_type (SCM name, SCM slots, scm_t_struct_finalize finalizer)

Create a fresh foreign object type. name is a symbol naming the type. slots is a list of symbols, each one naming a field in the foreign object type. finalizer indicates the finalizer, and may be NULL.

We recommend that finalizers be avoided if possible. See Foreign Object Memory Management. Finalizers must be async-safe and thread-safe. Again, see Foreign Object Memory Management. If you are embedding Guile in an application that is not thread-safe, and you define foreign object types that need finalization, you might want to disable automatic finalization, and arrange to call scm_manually_run_finalizers () yourself.

C Function: int scm_set_automatic_finalization_enabled (int enabled_p)

Enable or disable automatic finalization. By default, Guile arranges to invoke object finalizers automatically, in a separate thread if possible. Passing a zero value for enabled_p will disable automatic finalization for Guile as a whole. If you disable automatic finalization, you will have to call scm_run_finalizers () periodically.

Unlike most other Guile functions, you can call scm_set_automatic_finalization_enabled before Guile has been initialized.

Return the previous status of automatic finalization.

C Function: int scm_run_finalizers (void)

Invoke any pending finalizers. Returns the number of finalizers that were invoked. This function should be called when automatic finalization is disabled, though it may be called if it is enabled as well.

C Function: void scm_assert_foreign_object_type (SCM type, SCM val)

When val is a foreign object of the given type, do nothing. Otherwise, signal an error.

C Function: SCM scm_make_foreign_object_0 (SCM type)

C Function: SCM scm_make_foreign_object_1 (SCM type, void *val0)

C Function: SCM scm_make_foreign_object_2 (SCM type, void *val0, void *val1)

C Function: SCM scm_make_foreign_object_3 (SCM type, void *val0, void *val1, void *val2)

C Function: SCM scm_make_foreign_object_n (SCM type, size_t n, void *vals[])

Make a new foreign object of the type with type type and initialize the first n fields to the given values, as appropriate.

The number of fields for objects of a given type is fixed when the type is created. It is an error to give more initializers than there are fields in the value. It is perfectly fine to give fewer initializers than needed; this is convenient when some fields are of non-pointer types, and would be easier to initialize with the setters described below.

C Function: void* scm_foreign_object_ref (SCM obj, size_t n);

C Function: scm_t_bits scm_foreign_object_unsigned_ref (SCM obj, size_t n);

C Function: scm_t_signed_bits scm_foreign_object_signed_ref (SCM obj, size_t n);

Return the value of the nth field of the foreign object obj. The backing store for the fields is as wide as a scm_t_bits value, which is at least as wide as a pointer. The different variants handle casting in a portable way.

C Function: void scm_foreign_object_set_x (SCM obj, size_t n, void *val);

C Function: void scm_foreign_object_unsigned_set_x (SCM obj, size_t n, scm_t_bits val);

C Function: void scm_foreign_object_signed_set_x (SCM obj, size_t n, scm_t_signed_bits val);

Set the value of the nth field of the foreign object obj to val, after portably converting to a scm_t_bits value, if needed.

One can also access foreign objects from Scheme. See Foreign Objects and Scheme, for some examples.

(use-modules (system foreign-object))

Scheme Procedure: make-foreign-object-type name slots [#:finalizer=#f]

Make a new foreign object type. See the above documentation for scm_make_foreign_object_type; these functions are exactly equivalent, except for the way in which the finalizer gets attached to instances (an internal detail).

The resulting value is a GOOPS class. See GOOPS, for more on classes in Guile.

Scheme Syntax: define-foreign-object-type name constructor (slot ...) [#:finalizer=#f]

A convenience macro to define a type, using make-foreign-object-type, and bind it to name. A constructor will be bound to constructor, and getters will be bound to each of slot....