11.5.2 Defined bindings

The syntax define-foreign-pointer-wrapper defines a number of bindings associated to the struct type; all the defined bindings are prefixed by the identifier ?type-id or by $ followed by the identifier ?type-id.

Here only the bindings in the public API are documented:

(make-?type-id/owner pointer field …)

(make-?type-id/owner pointer collector field …)

Build and return a new struct instance of type ?type-id wrapping the pointer object pointer; the returned instance owns the pointer object.

If the definition of ?type-id includes a clause collector-struct-type with value #f: this maker function accepts a single argument.

If the definition of ?type-id includes a clause collector-struct-type with an identifier ?collector-id as value: this maker function accepts two arguments, the second being the instance of type ?collector-id or #f if there is no collector instance.

If the definition of ?type-id includes a clause fields: the constructor function accepts as many arguments as specified custom fields.

(make-?type-id/not-owner pointer field …)

(make-?type-id/not-owner pointer collector field …)

Build and return a new struct instance of type ?type-id wrapping the pointer object pointer; the returned instance does not own the pointer object.

If the definition of ?type-id includes a clause collector-struct-type with value #f: this maker function accepts a single argument.

If the definition of ?type-id includes a clause collector-struct-type with an identifier ?collector-id as value: this maker function accepts two arguments, the second being the instance of type ?collector-id or #f if there is no collector instance.

($?type-id-finalise struct)

Perform the finalisation procedure for this struct instance; it is safe to apply this finalisation function multiple times to the same struct instance: the first time the finalisation takes place, subsequent times nothing happens. The argument to this function must be an instance of ?type-id, else the behaviour is undefined.

The finalisation procedure involves the following:

1. If a custom destructor function has been registered: it is applied to struct before any finalisation takes place.
2. If struct has a collecting struct collector: struct is unregistered from collector.
3. If struct collects instances of another type: all the collected instances are finalised by invoking their unsafe finalisation functions; any exception raised by these finalisation functions is catched by guard and discarded.
4. If a foreign destructor function ?destructor-id was specified in the definition of ?type-id and this struct instance owns the pointer object: the foreign destructor is applied to struct; any exception raised by the destructor function is catched by guard and discarded. The return value of the foreign destructor becomes the return value of this function.
5. The internal field holding the pointer object is reset to #f, to mark this struct instance as already finalised.

About the returned value:

• If this is the first time the finalisation function is applied, there is a foreign destructor and its application is successful: the returned value is the return value from the foreign destructor.
• If this is the first time the finalisation function is applied, there is a foreign destructor and its application raises an exception: the returned value is #f.
• If this is not the first time the finalisation function is applied: the returned value is #f.

(?type-id? obj)

Type predicate function; it returns #t if obj is an instance of type ?type-id, otherwise it returns #f.

(?type-id?/alive obj)

Type and liveness predicate function; it returns #t if obj is an instance of type ?type-id and its pointer object has not yet been finalised, otherwise it returns #f.

NOTE The returned information really represents the status of the foreign data structure only for struct instances that do own the foreign pointer.

($?type-id-alive? struct)

Unsafe liveness predicate function; it returns #t if struct has a pointer object not yet finalised, otherwise it returns #f. The argument to this function must be an instance of ?type-id, else the behaviour is undefined.

NOTE The returned information really represents the status of the foreign data structure only for struct instances that do own the foreign pointer.

(?type-id obj)

Validation form to be used with the facilities of the library (vicare arguments validation). Succeed if obj satisfies the predicate ?type-id?.

(?type-id/alive obj)

Validation form to be used with the facilities of the library (vicare arguments validation). Succeed if obj satisfies the predicate ?type-id?/alive.

(false-or-?type-id obj)

Validation form to be used with the facilities of the library (vicare arguments validation). Succeed if obj is #f or satisfies the predicate ?type-id?.

(false-or-?type-id/alive obj)

Validation form to be used with the facilities of the library (vicare arguments validation). Succeed if obj is #f or satisfies the predicate ?type-id?/alive.

(?type-id-custom-destructor struct)

(set-?type-id-custom-destructor! struct destructor)

Retrieve or set a custom destructor function associated to struct. Whenever the struct is finalised: destructor is applied to struct before the internal state of struct is finalised.

(?type-id-pointer struct)

Return the pointer object referencing the foreign data structure; if struct has already been finalised: the returned value is #f.

(?type-id-pointer-owner? struct)

Return #t if struct owns the pointer object, otherwise return #f.

(?type-id-putprop struct key value)

Add a new property key with value to the property list of struct. If key is already set: the old entry is mutated to reference value. key must be a symbol.

(?type-id-getprop struct key)

Return the value of the property key in the property list of struct; if key is not set return #f. key must be a symbol.

(?type-id-remprop struct key)

Remove the property key from the property list of struct. key must be a symbol.

(?type-id-property-list struct)

Return a new association list representing the property list of struct.

(?type-id-hash struct)

Return an exact integer to be used as hashtable key for struct.

If the definition of ?type-id includes a clause collector-struct-type with an identifier ?collector-id as value, the following bindings are available:

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

Return the instance of type ?collector-id that was registered as collector for struct; if no collector was registered: return #f.

If the definition of ?type-id includes a clause collected-struct-type with an identifier ?collected-id as value, the following bindings are available:

($?type-id-register-?collected-id! collector struct)

Register struct in the internal table of collector. No arguments validation is peformed: collector must be of type ?type-id; struct must be of type ?collected-id.

($?type-id-forget-?collected-id! collector collected)

Remove collected from the internal table of collector. No arguments validation is peformed: collector must be of type ?type-id; collected must be of type ?collected-id.

($?type-id-contains-?collected-id? collector struct)

Query the internal table of collected and return true if struct is present, otherwise return false. No arguments validation is peformed: collector must be of type ?type-id.

($?type-id-vector-of-collected-?collected-id struct)

Return a Scheme vector containing the instances of type ?collected-id collected by struct.