NonmovableArrays

java.lang.Object
- com.oracle.svm.core.c.NonmovableArrays

```
public final class NonmovableArrays
extends Object
```
Support for allocating and accessing non-moving arrays. Such arrays are safe to access during garbage collection. They can also be passed between isolates, provided that they do not contain object references and that their lifecycle is managed correctly.
Non-moving arrays are created in unmanaged memory (for example, using NonmovableArrays.createByteArray(int)) and their owner must eventually manually release them. For object arrays, the owner must manually ensure that the contained object references are always visible. Although the memory layout of arrays might resemble that of Java arrays, they are not Java objects and must never be referenced as an object (with the exception for the image build below).
During image generation, the methods of this class create and access arrays that will reside in the image heap. Due to current restrictions, the backing objects must be referenced from fields via NonmovableArrays.getHostedArray(com.oracle.svm.core.c.NonmovableArray<?>) and they must be cast back via NonmovableArrays.fromImageHeap(java.lang.Object) at runtime.

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static <T extends org.graalvm.word.PointerBase> T`	`addressOf(NonmovableArray<?> array, int index)` Returns a pointer to the address of the given index of an array.
`static void`	`arraycopy(NonmovableArray<?> src, int srcPos, NonmovableArray<?> dest, int destPos, int length)`
`static ByteBuffer`	`asByteBuffer(NonmovableArray<Byte> array)` Obtain a ByteBuffer that is backed by the given array.
`static org.graalvm.word.UnsignedWord`	`byteSizeOf(NonmovableArray<?> array)` Provides the size of the given array in bytes.
`static <T> NonmovableObjectArray<T>`	`copyOfObjectArray(T[] source)` Same as `NonmovableArrays.copyOfObjectArray(T[], int)` with a `newLength` of the array length.
`static <T> NonmovableObjectArray<T>`	`copyOfObjectArray(T[] source, int newLength)`
`static NonmovableArray<Byte>`	`createByteArray(int nbytes)` Allocates a byte array of the specified length.
`static NonmovableArray<Integer>`	`createIntArray(int length)` Allocates an integer array of the specified length.
`static <T> NonmovableObjectArray<T>`	`createObjectArray(int length)` Allocates an array of the specified length to hold references to objects on the Java heap.
`static <T extends org.graalvm.word.WordBase> NonmovableArray<T>`	`createWordArray(int length)` Allocates a word array of the specified length.
`static <T> NonmovableArray<T>`	`fromImageHeap(Object array)` Returns a `NonmovableArray` for an array of primitives in the image heap.
`static <T> NonmovableObjectArray<T>`	`fromImageHeap(Object[] array)` Returns a `NonmovableObjectArray` for an object array in the image heap.
`static <T> T`	`getHostedArray(NonmovableArray<?> array)` During the image build, get the backing array that will be nonmovable in the image heap.
`static int`	`getInt(NonmovableArray<Integer> array, int index)` Reads the value at the given index in an array of `int`s.
`static <T> T`	`getObject(NonmovableObjectArray<T> array, int index)` Reads the value at the given index in an object array.
`static <T extends org.graalvm.word.WordBase> T`	`getWord(NonmovableArray<T> array, int index)` Reads the value at the given index in an array of words.
`static int`	`lengthOf(NonmovableArray<?> array)` Provides the length of an array in elements.
`static <T extends NonmovableArray<?>> T`	`nullArray()` Provides an array for which `PointerBase.isNull()` returns `true`.
`static void`	`releaseUnmanagedArray(NonmovableArray<?> array)` Releases an array created at runtime.
`static void`	`setInt(NonmovableArray<Integer> array, int index, int value)` Writes the value at the given index in an array of `int`s.
`static <T> void`	`setObject(NonmovableObjectArray<T> array, int index, T value)` Writes the value at the given index in an object array.
`static <T extends org.graalvm.word.WordBase> void`	`setWord(NonmovableArray<T> array, int index, T value)` Writes the value at the given index in an array of words.
`static void`	`tearDown()`
`static void`	`trackUnmanagedArray(NonmovableArray<?> array)` Begins tracking an array, e.g.
`static void`	`untrackUnmanagedArray(NonmovableArray<?> array)` Untracks an array created at runtime, e.g.
`static boolean`	`walkUnmanagedObjectArray(NonmovableObjectArray<?> array, ObjectReferenceVisitor visitor)` Visits all array elements with the provided `ObjectReferenceVisitor`.
`static boolean`	`walkUnmanagedObjectArray(NonmovableObjectArray<?> array, ObjectReferenceVisitor visitor, int startIndex, int count)` Visits all array elements with the provided `ObjectReferenceVisitor`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - trackUnmanagedArray
```
public static void trackUnmanagedArray(NonmovableArray<?> array)
```
    Begins tracking an array, e.g. when it is handed over from a different isolate.
  - lengthOf
```
public static int lengthOf(NonmovableArray<?> array)
```
    Provides the length of an array in elements.
  - byteSizeOf
```
public static org.graalvm.word.UnsignedWord byteSizeOf(NonmovableArray<?> array)
```
    Provides the size of the given array in bytes.
  - arraycopy
```
public static void arraycopy(NonmovableArray<?> src,
                             int srcPos,
                             NonmovableArray<?> dest,
                             int destPos,
                             int length)
```
    See Also:
    
    System.arraycopy(java.lang.Object, int, java.lang.Object, int, int)
  - nullArray
```
public static <T extends NonmovableArray<?>> T nullArray()
```
    Provides an array for which PointerBase.isNull() returns true.
  - createByteArray
```
public static NonmovableArray<Byte> createByteArray(int nbytes)
```
    Allocates a byte array of the specified length.
    The returned array must be accessed via methods of NonmovableArrays only, such as NonmovableArrays.asByteBuffer(com.oracle.svm.core.c.NonmovableArray<java.lang.Byte>). Although the array's memory layout might resemble that of a Java array, it is not a Java object and must never be referenced as an object.
  - createIntArray
```
public static NonmovableArray<Integer> createIntArray(int length)
```
    Allocates an integer array of the specified length.
    The returned array must be accessed via methods of NonmovableArrays only, such as NonmovableArrays.getInt(com.oracle.svm.core.c.NonmovableArray<java.lang.Integer>, int) and NonmovableArrays.setInt(com.oracle.svm.core.c.NonmovableArray<java.lang.Integer>, int, int). Although the array's memory layout might resemble that of a Java array, it is not a Java object and must never be referenced as an object.
  - createWordArray
```
public static <T extends org.graalvm.word.WordBase> NonmovableArray<T> createWordArray(int length)
```
    Allocates a word array of the specified length.
    The returned array must be accessed via methods of NonmovableArrays only, such as NonmovableArrays.getWord(com.oracle.svm.core.c.NonmovableArray<T>, int) and NonmovableArrays.setWord(com.oracle.svm.core.c.NonmovableArray<T>, int, T). Although the array's memory layout might resemble that of a Java array, it is not a Java object and must never be referenced as an object.
  - createObjectArray
```
public static <T> NonmovableObjectArray<T> createObjectArray(int length)
```
    Allocates an array of the specified length to hold references to objects on the Java heap. In order to ensure that the referenced objects are reachable for garbage collection, the owner of an instance must call NonmovableArrays.walkUnmanagedObjectArray(com.oracle.svm.core.c.NonmovableObjectArray<?>, com.oracle.svm.core.heap.ObjectReferenceVisitor) on each array from a GC-registered reference walker. The array must be released manually with NonmovableArrays.releaseUnmanagedArray(com.oracle.svm.core.c.NonmovableArray<?>).
    The returned array must be accessed via methods of NonmovableArrays only, such as NonmovableArrays.getObject(com.oracle.svm.core.c.NonmovableObjectArray<T>, int) and NonmovableArrays.setObject(com.oracle.svm.core.c.NonmovableObjectArray<T>, int, T). Although the array's memory layout might resemble that of a Java array, it is not a Java object and must never be referenced as an object.
  - copyOfObjectArray
```
public static <T> NonmovableObjectArray<T> copyOfObjectArray(T[] source,
                                                             int newLength)
```
    See Also:
    
    Arrays.copyOf(T[], int)
  - copyOfObjectArray
```
public static <T> NonmovableObjectArray<T> copyOfObjectArray(T[] source)
```
    Same as NonmovableArrays.copyOfObjectArray(T[], int) with a newLength of the array length.
  - releaseUnmanagedArray
```
public static void releaseUnmanagedArray(NonmovableArray<?> array)
```
    Releases an array created at runtime.
  - untrackUnmanagedArray
```
public static void untrackUnmanagedArray(NonmovableArray<?> array)
```
    Untracks an array created at runtime, e.g. before it is handed over to another isolate.
  - fromImageHeap
```
public static <T> NonmovableArray<T> fromImageHeap(Object array)
```
    Returns a NonmovableArray for an array of primitives in the image heap.
  - fromImageHeap
```
public static <T> NonmovableObjectArray<T> fromImageHeap(Object[] array)
```
    Returns a NonmovableObjectArray for an object array in the image heap.
  - getHostedArray
```
public static <T> T getHostedArray(NonmovableArray<?> array)
```
    During the image build, get the backing array that will be nonmovable in the image heap.
  - asByteBuffer
```
public static ByteBuffer asByteBuffer(NonmovableArray<Byte> array)
```
    Obtain a ByteBuffer that is backed by the given array.
  - getInt
```
public static int getInt(NonmovableArray<Integer> array,
                         int index)
```
    Reads the value at the given index in an array of ints.
  - setInt
```
public static void setInt(NonmovableArray<Integer> array,
                          int index,
                          int value)
```
    Writes the value at the given index in an array of ints.
  - setWord
```
public static <T extends org.graalvm.word.WordBase> void setWord(NonmovableArray<T> array,
                                                                 int index,
                                                                 T value)
```
    Writes the value at the given index in an array of words.
  - getWord
```
public static <T extends org.graalvm.word.WordBase> T getWord(NonmovableArray<T> array,
                                                              int index)
```
    Reads the value at the given index in an array of words.
  - addressOf
```
public static <T extends org.graalvm.word.PointerBase> T addressOf(NonmovableArray<?> array,
                                                                   int index)
```
    Returns a pointer to the address of the given index of an array.
  - getObject
```
public static <T> T getObject(NonmovableObjectArray<T> array,
                              int index)
```
    Reads the value at the given index in an object array.
  - setObject
```
public static <T> void setObject(NonmovableObjectArray<T> array,
                                 int index,
                                 T value)
```
    Writes the value at the given index in an object array.
  - walkUnmanagedObjectArray
```
public static boolean walkUnmanagedObjectArray(NonmovableObjectArray<?> array,
                                               ObjectReferenceVisitor visitor)
```
    Visits all array elements with the provided ObjectReferenceVisitor.
  - walkUnmanagedObjectArray
```
public static boolean walkUnmanagedObjectArray(NonmovableObjectArray<?> array,
                                               ObjectReferenceVisitor visitor,
                                               int startIndex,
                                               int count)
```
    Visits all array elements with the provided ObjectReferenceVisitor.
  - tearDown
```
public static void tearDown()
```

Class NonmovableArrays

Method Summary

Methods inherited from class java.lang.Object

Method Detail

trackUnmanagedArray

lengthOf

byteSizeOf

arraycopy

nullArray

createByteArray

createIntArray

createWordArray

createObjectArray

copyOfObjectArray

copyOfObjectArray

releaseUnmanagedArray

untrackUnmanagedArray

fromImageHeap

fromImageHeap

getHostedArray

asByteBuffer

getInt

setInt

setWord

getWord

addressOf

getObject

setObject

walkUnmanagedObjectArray

walkUnmanagedObjectArray

tearDown