with-pinned-objects

with-pinned-objects Macro

Summary

Prevents objects from moving while in the dynamic scope of some code.

Package

hcl

Signature

with-pinned-objects (&rest objects) &body body => body-result*

Arguments

`objects`⇩	"Pinnable" Lisp objects.
`body`⇩	Lisp forms.

Values

body-result*

The values returned by body.

Description

The macro with-pinned-objects "pins" the objects in objects while executing the form of body. Pinning means that the objects do not move.

Each element in objects is evaluated, and must produce an object suitable for pinning, which means either a static object or a "pinnable" object. Such objects are the result of calling make-array with the keyword :allocation being one of :static, :static-new or :pinnable.

with-pinned-objects signals an error if any element of objects is not suitable for pinning. It also prevents the elements of objects from being garbage collected while body executes.

with-pinned-objects is intended to be used for objects that are passed directly to foreign functions using the foreign type :lisp-array. Such objects must not be moved during the foreign call, so must be either static objects, or "pinnable" objects that are pinned dynamically by with-pinned-objects. Note that the foreign type :lisp-simple-1d-array implicitly pins the object, so there is no need to use with-pinned-objects for arguments that are passed with :lisp-simple-1d-array.

with-pinned-objects adds overhead to any garbage collections that occur while body is executed, so should be used with the smallest scope possible.

Pinning of an object has a global effect, but it is a thread-specific operation, so you cannot pin an object on one thread, and then rely on it being pinned on another thread.

The same object can be concurrently pinned multiple times on different threads or pinned recursively.