foreign-slot-value Accessor

Summary

Returns the value of a slot in a foreign object.

Package

fli

Signature

foreign-slot-value object slot-name &key type object-type copy-foreign-object => value

setf (foreign-slot-value object slot-name &key type object-type copy-foreign-object) value => value

Arguments

Values

Description

The accessor foreign-slot-value accesses and returns the value of a slot in a specified object. An error is signaled if the slot is an aggregate type and copy-foreign-object is not supplied as t or nil. Use foreign-slot-pointer to access such aggregate slots.

If slot-name is a symbol then it names the slot of object to be accessed. If slot-name is a list of symbols, then these symbols name slots in nested structures starting with the outermost structure object, as in the inner/middle/outer example below.

If type is supplied, then foreign-slot-value assumes that the slot contains an object of that type, overriding the type in the structure definition.

copy-foreign-object is only used when the type of the slot (or type if supplied) is an aggregate type, because objects of these types cannot be converted to a Lisp value. If copy-foreign-object is t, foreign-slot-value makes a copy of the aggregate object in the slot and returns the copy. If copy-foreign-object is nil, foreign-slot-value returns the aggregate object directly. If copy-foreign-object is :error (the default) then foreign-slot-value signals an error.

If object-type is supplied then foreign-slot-value assumes that object is of the that type and the compiler might be able to optimize the access to the slot. If object-type is not supplied, then the object type is determined dynamically from object.

The setf form of foreign-slot-value can be used to set the value of a slot in a structure, as shown in the example below.

Compatibility note

64-bit integer types such as (:long :long), :int64 and :uint64 are now supported for type in foreign-slot-value in 32-bit LispWorks. In 32-bit LispWorks 6.1 and earlier versions, these types could only be used by define-foreign-function.

Examples

In the following example a foreign structure is defined, an instance of the structure is made with my-pos pointing to the instance, and foreign-slot-value is used to set the y slot of the object to 10.

(fli:define-c-struct POS
  (x :int)
  (y :int)
  (z :int))

(setq my-pos (fli:allocate-foreign-object :type 'POS))

(setf (fli:foreign-slot-value my-pos 'y) 10)

The next forms both return the value of the y slot at my-pos, which is 10.

(fli:foreign-slot-value my-pos 'y)

(fli:foreign-slot-value my-pos 'y :object-type 'pos)

See section 9.7 Optimizing your code in the LispWorks® User Guide and Reference Manual in the LispWorks® User Guide and Reference Manual section "Optimizing your code" for an example showing how to inline foreign slot access.

This example accesses a slot in nested structures:

(fli:define-c-struct inner
  (v1 :int)
  (v2 :int))
 
(fli:define-c-struct middle
  (i1 (:struct inner))
  (i2 (:struct inner)))
 
(fli:define-c-struct outer
  (m1 (:struct middle))
  (m2 (:struct middle)))
 
(fli:with-dynamic-foreign-objects
    ((obj (:struct outer)))
  (setf (fli:foreign-slot-value obj '(m1 i2 v1)) 99))

See also

2.2.3 Structures and unions
foreign-slot-pointer
foreign-slot-offset
dereference
with-foreign-slots