org.graalvm.nativeimage

Interface PinnedObject

All Superinterfaces:

AutoCloseable

public interface PinnedObject
extends AutoCloseable

Holder for a pinned object, such that the object doesn't move until the pin is removed. The garbage collector treats pinned object specially to ensure that they are not moved or discarded.

This class implements AutoCloseable so that the pinning can be managed conveniently with a try-with-resource block that releases the pinning automatically:

   int[] array = ...
   try (PinnedObject pin = PinnedObject.create(array)) {
     CIntPointer rawData = pin.addressOfArrayElement(0);
     // it is safe to pass rawData to a C function.
   }
   // it is no longer safe to access rawData.
 

Since:

19.0

Method Summary

Modifier and Type	Method and Description
<T extends PointerBase> T	addressOfArrayElement(int index) Returns a pointer to the array element with the specified index.
PointerBase	addressOfObject() Returns the raw address of the pinned object.
void	close() Releases the pin for the object.
static PinnedObject	create(Object object) Create an open PinnedObject.
Object	getObject() Returns the Object that is the referent of this PinnedObject.

Method Detail

create

static PinnedObject create(Object object)

Create an open PinnedObject.

Since:

19.0

close

void close()

Releases the pin for the object. After this call, the object can be moved or discarded by the garbage collector.

Specified by:

close in interface AutoCloseable

Since:

19.0

getObject

Object getObject()

Returns the Object that is the referent of this PinnedObject.

Since:

19.0

addressOfObject

PointerBase addressOfObject()

Returns the raw address of the pinned object. The object layout is not specified, but usually the address of an object is a pointer to to the first header word. In particular, the result is not a pointer to the first array element when the object is an array.

Since:

19.0

addressOfArrayElement

<T extends PointerBase> T addressOfArrayElement(int index)

Returns a pointer to the array element with the specified index. The object must be an array. No array bounds check for the index is performed.

Since:

19.0