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

    • 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