Passes a foreign object of a specified type by reference, and automatically dereferences the object.
The type of the object to pass by reference.
If non-
nil
, if the input argument is
nil
a null pointer is passed instead of a reference to an object containing
nil
.
If non-
nil
, allow conversion from Lisp to the foreign language. The default value is
t
.
If non-
nil
, allow conversion from the foreign language to Lisp. The default value is
t
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
(:reference
type
)
, 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-p
is
nil
, and similarly, the return value is not copied back into a Lisp object if
foreign-to-lisp-p
is
nil
.
In the following example an
:int
is allocated, and a pointer to the integer is bound to the Lisp variable
number
. Then a pointer to
number
, called
point1
, is defined. The pointer
point1
is set to point to
number
, 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 :int)))
(setf (fli:dereference point1) number)
If
point1
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 dereference
point1
as a
:reference
, we only have to dereference it once to get the value:
(fli:dereference point1 :type '(:reference :int))