Macro

Summary

Creates a dynamic-extent foreign pointer which points to the data in a given Lisp array while the forms are executed.

Package

fli

Signature

with-dynamic-lisp-array-pointer ( pointer-var lisp-array &key start type ) &body body => last

Arguments

pointer-var

A variable to be bound to the foreign pointer.

lisp-array

A Lisp array.

start

An index into the Lisp array. The default is 0 .

type

A foreign type. The default is :void .

body

A list of forms.

Values

last

The value of the last form in body .

Description

The macro with-dynamic-lisp-array-pointer enables the data in a Lisp array (a string or a byte array) to be shared directly with foreign code, without making a copy. A dynamic-extent pointer to the array's data can be used within body wherever the :pointer foreign type allows.

with-dynamic-lisp-array-pointer creates a dynamic extent foreign pointer, with element type type , which is initialized to point to the element of lisp-array at index index .

This foreign pointer is bound to pointer-var , the forms of body are executed and the value of the last form returned.

Pointers created with this macro must be used with care. There are three restrictions:

1. lisp-array must be static, for example allocated within sys:in-static-area .
2. The pointer has dynamic extent and lisp-array is guaranteed to be preserved only during the execution of body . If you keep the value of the pointer, you must also preserve lisp-array, that is you must ensure it is not garbage-collected.
3. Lisp strings and arrays are not null-terminated, therefore foreign code must only access the data of lisp-array up to its known length.

Example

(let ((vector 

       (sys:in-static-area

        (make-array 3 :element-type '(unsigned-byte 8)

                    :initial-contents '(65 77 23)))))

  (fli:with-dynamic-lisp-array-pointer 

      (ptr vector :start 1 :type :unsigned-byte)

    (fli:dereference ptr)))

=> 

77

See also

:lisp-array