All Manuals > Foreign Language Interface User Guide and Reference Manual > 7 Function, Macro and Variable Reference

with-dynamic-lisp-array-pointer 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 static or pinned Lisp array (a string or a byte/single-float/double-float array).
start
An index into the Lisp array.
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 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 start. The default value of start is 0.

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

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

  1. lisp-array must be static or pinned, for example allocated as shown below.
  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.
Examples

An example of using a static array:

(let ((vector 
       (make-array 3 :element-type '(unsigned-byte 8)
                   :initial-contents '(65 77 23)
                   :allocation :static)))
  (fli:with-dynamic-lisp-array-pointer 
      (ptr vector :start 1 :type '(:unsigned :byte))
    (fli:dereference ptr)))
=> 
77

An example of using a pinned array:

(let ((vector 
       (make-array 3 :element-type '(unsigned-byte 8)
                   :initial-contents '(65 77 23)
                   :allocation :pinnable)))
  (with-pinned-objects (vector)
    (fli:with-dynamic-lisp-array-pointer 
        (ptr vector :start 1 :type '(:unsigned :byte))
      (fli:dereference ptr))))
=> 
77
See also

:lisp-array
:lisp-simple-1d-array
with-pinned-objects


Foreign Language Interface User Guide and Reference Manual - 01 Dec 2021 19:34:58