3.2.4 Wrapping a C Pointer Type

G-Wrap comes with a generic wrapped type for wrapping C pointers which is called the wrapped C type, or WCT for short. Within G-Wrap, WCTs are represented by the <gw-wct> class, defined in the (g-wrap c-types) module. Instances of a WCT are called wrapped C pointers, or WCPs for short.

Any C pointer type may be wrapped using the wrap-as-wct! method. This method allows to specify a number of useful information specific to the C pointer type being wrapped, such as what action should be taken when a WCP gets garbage-collected.

method: wrap-as-wct! (wrapset <gw-wrapset>) . args

Adds the C pointer type defined by args to the list of types to be wrapped by wrapset. The arguments in args must contain the following named parameters:

#:name

a symbol specifying a Scheme-level name for this type.

#:c-type-name

a string representing the C pointer type, such as "chbouib_t *".

#:c-const-type-name

a string representing the const-qualified version of the C pointer type, such as "const chbouib_t *".

Optionally, args may contain the following parameters:

#:wcp-equal-predicate

A string representing a pointer to a C function of type int (*) (void *, void *). This C function will be called whenever comparing, via equal? (see Equality in The GNU Guile Reference Manual), two WCP objects of the type being wrapped. It should return true (i.e., non-zero) whenever the two C objects pointed to by the void * pointers are equal, false otherwise.

#:wcp-free-function

A string representing a pointer to a C function of type size_t (*) (void *wcp). This C function will be called whenever a WCP of this type is garbaged-collected and will be passed the C pointer wrapped by this WCP.

#:wcp-mark-function

A string representing a pointer to a C function of type SCM (*) (SCM wcp). This is a non-portable feature that is relevant only to wrapsets targeting Guile.

Guile’s garbage-collector uses a mark and sweep algorithm (see the description of Guile’s GC mechanism in The GNU Guile Reference Manual). This parameter allows to direct the mark phase for the specific C type being wrapped, using the same protocol as the one used for SMOBs in Guile.

This option is only useful when wrapping C types that aggregate objects of type SCM: during the mark phase of the GC, SCM objects referenced by instances of such a type will need to be marked, too. Suppose, for instance, the following C type:

typedef struct
{
  int   count;
  float average;
  SCM   scheme_thing;
} chbouib_t;

When the GC marks a WCP wrapping a chbouib_t pointer, you will also want it to mark the Scheme object contained in its scheme_thing field. Using #:wcp-mark-function, you can specify a mark function for your WCT such that the scheme_thing field does get marked.

#:description

A string describing this wrapped C type.