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, for details), 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 see the description of Guile's GC mechanism, for details). 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.