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

object

Either an instance of or a pointer to a FLI structure.

slot-name

A symbol or a list of symbols identifying the slot to be accessed.

type

The type of value. Specifying type makes accessing the object faster. If the specified type is different to the actual type, foreign-slot-value returns the value in the format of type where possible.

object-type

The FLI structure type that contains slot-name. If this is passed, the compiler might be able to optimize the access to the slot. If this is omitted, the object type is determined dynamically from object.

copy-foreign-object

This option is only important when dealing with slots which are aggregate FLI types, and cannot be returned by value. The recognized values are t, nil and :error:

If copy-foreign-object is t, foreign-slot-value makes a copy of the aggregate slot of the object pointed to by pointer and returns the copy.

If copy-foreign-object is nil, foreign-slot-value returns the aggregate slot of the object directly.

If copy-foreign-object is :error then foreign-slot-value signals an error. This is the default value for copy-foreign-object.

Value

value

The value of the slot slot-name in the FLI object object is returned.

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 set accordingly. 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.

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.

Example

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 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

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