translate-to-foreign

Next: with-foreign-slots, Previous: translate-from-foreign, Up: Foreign Types

Syntax

— Generic Function: translate-to-foreign lisp-value type-name ⇒ foreign-value, alloc-param

Arguments and Values

lisp-value: The Lisp value to convert to foreign representation.
type-name: A symbol naming a foreign type defined by defctype.
foreign-value: The foreign value to pass in place of lisp-value to foreign code.
alloc-param: If present, this value will be passed to free-translated-object.

Description

This generic function is invoked by CFFI to convert a Lisp value to a foreign value, such as when passing arguments to a foreign function, returning a value from a callback, or setting a foreign variable. A “foreign value” is one appropriate for passing to the next-lowest translator, including the low-level translators that are ultimately invoked invisibly with CFFI.

To extend the CFFI type system by performing custom translations, this method may be specialized by eql-specializing type-name on a symbol naming a foreign type defined with defctype. This method should return the appropriate foreign value to use in place of the Lisp value.

In cases where CFFI can determine the lifetime of the foreign object returned by this method, it will invoke free-translated-object on the foreign object at the appropriate time. If translate-to-foreign returns a second value, it will be passed as the param argument to free-translated-object. This can be used to establish communication between the allocation and deallocation methods.

The results are undefined if the type-name parameter is specialized in any way except an eql specializer on a foreign type defined with defctype. Specifically, translations may not be defined for built-in types.