2.4 Encapsulated types

With earlier version of the foreign function interface it was not possible to create new foreign types that encapsulated the functionality of existing types. The only way in which types could be abstracted was to create "wrapper" functions that filtered the uses of a given type. The FLI contains the ability to encapsulate foreign types, along with the ability to create parameterized types. This enables you to easily create more advanced and powerful type definitions.

2.4.1 Passing Lisp objects to C

There are occasions when it is necessary to pass Lisp object references through to C and then back into Lisp again. An example of this is the need to specify Lisp arguments for a GUI action callback.

Using either the foreign type :wrapper or the macro define-foreign-converter a new foreign type can be created that wraps an extra level of conversion around the Lisp to C or C to Lisp process.

2.4.2 An example

For example, let us assume that we want to pass Lisp object handles through to C and then back to Lisp again. Passing C a pointer to the Lisp object is not sufficient, as the Lisp object might be moved at any time, for example due to garbage collection. Instead, we could assign each Lisp object to be passed to C a unique int handle. Callbacks into Lisp could then convert the handle back into the Lisp object. This example is implemented in two ways: using the :wrapper type and using define-foreign-converter.

The :wrapper foreign type allows the specification of automatic conversion functions between Lisp and an instance of a FLI type. Its signature is:

:wrapper fli-type &key lisp-to-foreign foreign-to-lisp

Using :wrapper we can wrap Lisp to C and C to Lisp converters around the converters of an existing type:

(fli:define-foreign-type lisp-object-wrapper ()
  "A mechanism for passing a Lisp object handle to C.
   Underlying C type is Lint"
 `(:wrapper :int
   :lisp-to-foreign find-index-for-object
   :foreign-to-lisp find-object-from-index))

If the :lisp-to-foreign and :foreign-to-lisp keyword arguments are not specified, no extra conversion is applied to the underlying foreign type, causing it to behave like a standard :int type.

See the reference entry for :wrapper for more examples.

A second method uses define-foreign-converter, which is specifically designed for the creation of new converter types (that is, types which wrap extra levels of conversion around existing types). A simple use of define-foreign-converter is to only wrap extra levels of conversion around existing Lisp to foreign and foreign to Lisp converters.

(fli:define-foreign-converter lisp-object-wrapper () object
  :foreign-type :int
  :lisp-to-foreign `(find-index-for-object ,object)
;; object will be the Lisp Object
  :foreign-to-lisp `(find-object-from-index ,object)
;; object will be the :int object
  :documentation "Foreign type for converting from Lisp objects to
integers handles to Lisp objects which can then be manipulated in
C. Underlying foreign type : 'C' int")

The definition of lisp-object-wrapper using define-foreign-converter is very similar to the definition using :wrapper, and indeed the :wrapper type could be defined using define-foreign-converter.

See the reference entry for define-foreign-converter for more information.