3.3.3 Wrapping and Unwrapping Values

For each specific wrapped type, a specific sequence of C code must be issued to wrap (i.e. convert a C value to a Scheme value) and unwrap (i.e. convert a Scheme value to C) values of this type. The high-level API offers a way to specify this via wrap-simple-type! (see Wrapping Another Simple C Type). However, G-Wrap’s native code generation protocols is much more flexible that this.

The methods described below are those that direct the generation of wrapping/unwrapping C code for values of a given wrapped type.

method: wrap-value-cg (type <gw-type>) (value <gw-value>) err (inlined? <boolean>)

Generate C code that wraps the value value of type type. err is a string containing the name of the C variable holding a G-Wrap run-time error (see Overview of the Code Generation Methods).

If inlined? is false, then this means that the wrapping code is generated for use in a stand-alone wrapping function for type. Generation of code for stand-alone wrapping functions is performed by wrap-value-function-cg (see below).

If inlined? is true, then this means that wrapping code is generated for use within a C function wrapper. C function wrapper code generation is performed by function-wrapper-cg for functions where run-time type information cannot be relied on (FIXME: xref).

When wrapping code is generated within a function wrapper, then certain assumptions can be made that cannot be made in the case of stand-alone wrapping functions. For instance, it can be assumed that storage for the wrapped value can be allocated on the stack rather than on the heap, in order to speed up operation.

As an example, unwrap-value-cg method for type mchars, for Guile wrapsets, can convert Scheme strings to C strings on the stack using scm_to_locale_stringbuf rather than scm_to_locale_string which allocates a new C string on the heap (see Guile string wrapping/unwrapping in The GNU Guile Reference Manual). The inline? argument is optional. This means that you can overload wrap-value-cg without having to specify this argument:

(define-method (wrap-value-cg (type <my-own-type>) (value <gw-value>)
                              error-var)
  ;; Always generate the same code, whether it is generated in a
  ;; stand-alone wrapping function or not.
  )

method: unwrap-value-cg (type <gw-type>) (value <gw-value>) err (inlined? <boolean>)

Generate C code that unwraps the value value of type type. err is a string containing the name of the C variable holding a G-Wrap run-time error.

The interpretation of inlined? is the same as for wrap-value-cg and it is also optional.

method: destroy-value-cg (type <gw-type>) (value <gw-value>) err (inlined? <boolean>)

Generate C code that destroys the value value of type type. value is assumed to be a C value previously unwrapped by the code generated by unwrap-value-cg. err is a string containing the name of the C variable holding a G-Wrap run-time error.

The interpretation of inlined? is the same as for wrap-value-cg and it is also optional.

method: wrap-value-function-cg (type <gw-rti-type>)

Generate a stand-alone C function that wraps values of type type, a type for which information is available at run-time.

Since G-Wrap allows to construct function calls at run-time via libffi (FIXME: xref), such stand-alone wrapping functions are used by the run-time call constructor.