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.
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.
: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:
: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.
See the reference entry for define-foreign-converter for more information.
LispWorks Foreign Language Interface User Guide and Reference Manual - 29 Sep 2017