6 Type Reference

:reference

FLI type descriptor

Summary

Passes a foreign object of a specified type by reference, and automatically dereferences the object.

Package

fli

Syntax

:reference type &key allow-null lisp-to-foreign-p foreign-to-lisp-p

Arguments

type: The type of the object to pass by reference.
allow-null: If non-nil, if the input argument isnil a null pointer is passed instead of a reference to an object containingnil.
lisp-to-foreign-p: If non-nil, allow conversion from Lisp to the foreign language. The default value ist.
foreign-to-lisp-p: If non-nil, allow conversion from the foreign language to Lisp. The default value ist

Description

The FLI:reference type is essentially the same as a:pointer type, except that:reference is automatically dereferenced when it is processed.

The:reference type is useful as a foreign function argument. When a function is called with an argument of the type(:referencetype), an object of type is dynamically allocated across the scope of the foreign function, and is automatically de-allocated once the foreign function terminates. The value of the argument is not copied into the temporary instance of the object if lisp-to-foreign isnil, and similarly, the return value is not copied back into a Lisp object if foreign-to-lisp isnil.

Example

In the following example an:int is allocated, and a pointer to the integer is bound to the Lisp variablenumber. Then a pointer tonumber, calledpoint1, is defined. The pointerpoint1 is set to point tonumber, itself a pointer, but to an:int.

(setq number (fli:allocate-foreign-object :type :int))

(setf (fli:dereference number) 42)

(setq point1 (fli:allocate-foreign-object 
              :type '(:pointer :pointer)))

(setf (fli:dereference point1) number)

: Ifpoint1 is dereferenced, it returns a pointer to an:int. To get at the value stored in the integer, we need to dereference twice:

(fli:dereference (fli:dereference point1))

: However, if we dereferencepoint1 as a:reference, we only have to dereference it once to get the value:

(fli:dereference point1 :type '(:reference :int))

See Also
: :reference-pass
: :reference-return