11.5.1 Defining wrapper structures

The following bindings are exported by the library (vicare ffi foreign-pointer-wrapper).

Syntax: define-foreign-pointer-wrapper ?type-id ?fields-clause ?destructor-clause ?collector-clause ?collected-clause …

Auxiliary Syntax: fields

Auxiliary Syntax: foreign-destructor

Auxiliary Syntax: collector-struct-type

Auxiliary Syntax: collected-struct-type

Wrapper for define-struct from (vicare) defining a struct type with some opaque fields. ?type-id must be an identifier representing the name of the struct type.

Two categories of struct instances exist: those who own the foreign data structure referenced by the pointer object; those who do not own the foreign data structure referenced by the pointer object. There are situations where the latter data structures are unsafe to use; Vicare discharges on the application the responsibility of using or not using such structures.

?fields-clause

This clause is optional. It must have one of the forms:

(fields)
(fields field-id ...)

where fields is the auxiliary keyword exported by (rnrs rnrs (6)) and the field-id are field name identifiers. The listed fields become normal fields of the defined structure.

?destructor-clause

It must have one of the forms:

(foreign-destructor #f)
(foreign-destructor ?destructor-id)

where ?destructor-id must be an identifier bound to the foreign data structure destructor Scheme function; when the value in the clause is #f: the data struct has no destructor function.

Whenever a struct instance owning the pointer object is finalised: the referenced destructor function is applied to the Scheme data struct; its responsibility is to extract the pointer object and apply to it whatever finalisation procedure the foreign library provides.

?collector-clause

It must have one of the forms:

(collector-struct-type #f)
(collector-struct-type ?collector-id)

where ?collector-id must be an identifier representing the name of another data struct type defined with this syntax; when the value of the clause is #f: ?type-id has no collector struct type.

Instances of ?type-id are meant to be, in some way, subordinate to ?collector-id; when building a new instance of type ?type-id, it is possible, but not mandatory, to specify an instance of type ?collector-id that “collects” it:

• Whenever the instance of type ?collector-id is finalised: the collected instances of type ?type-id are finalised too.
• Whenever the instance of type ?type-id is finalised: it unregisters itself from the collection in the instance of type ?collector-id.

?collected-clause

These clauses are optional and can be present in any number; when used, they must have the form:

(collected-struct-type ?collected-id)

where ?collected-id must be an identifier representing the name of another data struct type defined with this syntax.

Instances of ?collected-id are meant to be, in some way, subordinate to ?type-id; when building a new insance of type ?collected-id, it is possible, but not mandatory, to specify an instance of ?type-id that “collects” it:

• Whenever the instance of type ?type-id is finalised: the collected instances of type ?collected-id are finalised too.
• Whenever the instance of type ?collected-id is finalised: it unregisters itself from the collection in the instance of type ?type-id.