+ * All implementations of this interface must be value-based; + * use of identity-sensitive operations (including reference equality ({@code ==}), identity hash code, or synchronization) on + * instances of {@code MemorySegment} may have unpredictable results and should be avoided. The {@code equals} method should + * be used for comparisons. + *
+ * Non-platform classes should not implement {@linkplain MemorySegment} directly. + * + *
+ * It is also possible to obtain a memory segment backed by an existing heap-allocated Java array, + * using one of the provided factory methods (e.g. {@link MemorySegment#ofArray(int[])}). Memory segments obtained + * in this way are called array memory segments. + *
+ * It is possible to obtain a memory segment backed by an existing Java byte buffer (see {@link ByteBuffer}), + * using the factory method {@link MemorySegment#ofByteBuffer(ByteBuffer)}. + * Memory segments obtained in this way are called buffer memory segments. Note that buffer memory segments might + * be backed by native memory (as in the case of native memory segments) or heap memory (as in the case of array memory segments), + * depending on the characteristics of the byte buffer instance the segment is associated with. For instance, a buffer memory + * segment obtained from a byte buffer created with the {@link ByteBuffer#allocateDirect(int)} method will be backed + * by native memory. + *
+ * Finally, it is also possible to obtain a memory segment backed by a memory-mapped file using the factory method + * {@link MemorySegment#mapFromPath(Path, long, FileChannel.MapMode)}. Such memory segments are called mapped memory segments. + * + *
+ * If a memory segment S owned by thread A needs to be used by thread B, B needs to explicitly acquire S, + * which will create a so called acquired memory segment owned by B (see {@link #acquire()}) backed by the same resources + * as S. A memory segment can be acquired multiple times by one or more threads; in that case, a memory segment S cannot + * be closed until all the acquired memory segments derived from S have been closed. Furthermore, closing an acquired + * memory segment does not trigger any deallocation action. It is therefore important that clients remember to + * explicitly close the original segment from which the acquired memory segments have been obtained in order to truly + * ensure that off-heap resources associated with the memory segment are released. + * + *
+ * Temporal bounds of the original segment are inherited by the view; that is, closing a segment view, such as a sliced + * view, will cause the original segment to be closed; as such special care must be taken when sharing views + * between multiple clients. If a client want to protect itself against early closure of a segment by + * another actor, it is the responsibility of that client to take protective measures, such as calling + * {@link MemorySegment#acquire()} before sharing the view with another client. + *
+ * To allow for interoperability with existing code, a byte buffer view can be obtained from a memory segment + * (see {@link #asByteBuffer()}). This can be useful, for instance, for those clients that want to keep using the + * {@link ByteBuffer} API, but need to operate on large memory segments. Byte buffers obtained in such a way support + * the same spatial and temporal access restrictions associated to the memory address from which they originated. + * + * @apiNote In the future, if the Java language permits, {@link MemorySegment} + * may become a {@code sealed} interface, which would prohibit subclassing except by + * explicitly permitted types. + * + * @implSpec + * Implementations of this interface are immutable and thread-safe. + */ +public interface MemorySegment extends AutoCloseable { + + /** + * The base memory address associated with this memory segment. + * @return The base memory address. + */ + MemoryAddress baseAddress(); + + /** + * Obtains an acquired memory segment which can be used to access memory associated + * with this segment from the current thread. As a side-effect, this segment cannot be closed until the acquired + * view has been closed too (see {@link #close()}). + * @return an acquired memory segment which can be used to access memory associated + * with this segment from the current thread. + * @throws IllegalStateException if this segment has been closed. + */ + MemorySegment acquire(); + + /** + * Is this segment accessible from the current thread? + * @return true, if this segment is accessible from the current thread. + */ + boolean isAccessible(); + + /** + * The size (in bytes) of this memory segment. + * @return The size (in bytes) of this memory segment. + */ + long byteSize(); + + /** + * Obtains a read-only view of this segment. An attempt to write memory associated with a read-only memory segment + * will fail with {@link UnsupportedOperationException}. + * @return a read-only view of this segment. + * @throws IllegalStateException if this segment has been closed, or if access occurs from a thread other than the + * thread owning this segment. + */ + MemorySegment asReadOnly(); + + /** + * Obtains a new memory segment view whose base address is the same as the base address of this segment plus a given offset, + * and whose new size is specified by the given argument. + * @param offset The new segment base offset (relative to the current segment base address), specified in bytes. + * @param newSize The new segment size, specified in bytes. + * @return a new memory segment view with updated base/limit addresses. + * @throws IndexOutOfBoundsException if {@code offset < 0}, {@code offset > byteSize()}, {@code newSize < 0}, or {@code newSize > byteSize() - offset} + * @throws IllegalStateException if this segment has been closed, or if access occurs from a thread other than the + * thread owning this segment. + */ + MemorySegment asSlice(long offset, long newSize); + + /** + * Is this segment alive? + * @return true, if the segment is alive. + * @see MemorySegment#close() + */ + boolean isAlive(); + + /** + * Is this segment read-only? + * @return true, if the segment is read-only. + * @see MemorySegment#asReadOnly() + */ + boolean isReadOnly(); + + /** + * Closes this memory segment. Once a memory segment has been closed, any attempt to use the memory segment, + * or to access the memory associated with the segment will fail with {@link IllegalStateException}. Depending on + * the kind of memory segment being closed, calling this method further trigger deallocation of all the resources + * associated with the memory segment. + * @throws IllegalStateException if this segment has been closed, or if access occurs from a thread other than the + * thread owning this segment, or if existing acquired views of this segment are still in use (see {@link MemorySegment#acquire()}). + */ + void close(); + + /** + * Wraps this segment in a {@link ByteBuffer}. Some of the properties of the returned buffer are linked to + * the properties of this segment. For instance, if this segment is immutable + * (see {@link MemorySegment#asReadOnly()}, then the resulting buffer is read-only + * (see {@link ByteBuffer#isReadOnly()}. Additionally, if this is a native memory segment, the resulting buffer is + * direct (see {@link ByteBuffer#isDirect()}). + *
+ * The life-cycle of the returned buffer will be tied to that of this segment. That means that if the this segment + * is closed (see {@link MemorySegment#close()}, accessing the returned + * buffer will throw an {@link IllegalStateException}. + *
+ * The resulting buffer's byte order is {@link java.nio.ByteOrder#BIG_ENDIAN}; this can be changed using + * {@link ByteBuffer#order(java.nio.ByteOrder)}. + * + * @return a {@link ByteBuffer} view of this memory segment. + * @throws UnsupportedOperationException if this segment cannot be mapped onto a {@link ByteBuffer} instance, + * e.g. because it models an heap-based segment that is not based on a {@code byte[]}), or if its size is greater + * than {@link Integer#MAX_VALUE}. + * @throws IllegalStateException if this segment has been closed, or if access occurs from a thread other than the + * thread owning this segment. + */ + ByteBuffer asByteBuffer(); + + /** + * Copy the contents of this memory segment into a fresh byte array. + * @return a fresh byte array copy of this memory segment. + * @throws UnsupportedOperationException if this segment's contents cannot be copied into a {@link byte[]} instance, + * e.g. its size is greater than {@link Integer#MAX_VALUE}. + * @throws IllegalStateException if this segment has been closed, or if access occurs from a thread other than the + * thread owning this segment. + */ + byte[] toByteArray(); + + /** + * Creates a new buffer memory segment that models the memory associated with the given byte + * buffer. The segment starts relative to the buffer's position (inclusive) + * and ends relative to the buffer's limit (exclusive). + *
+ * The resulting memory segment keeps a reference to the backing buffer, to ensure it remains reachable + * for the life-time of the segment. + * + * @param bb the byte buffer backing the buffer memory segment. + * @return a new buffer memory segment. + */ + static MemorySegment ofByteBuffer(ByteBuffer bb) { + return Utils.makeBufferSegment(bb); + } + + /** + * Creates a new array memory segment that models the memory associated with a given heap-allocated byte array. + *
+ * The resulting memory segment keeps a reference to the backing array, to ensure it remains reachable + * for the life-time of the segment. + * + * @param arr the primitive array backing the array memory segment. + * @return a new array memory segment. + */ + static MemorySegment ofArray(byte[] arr) { + return Utils.makeArraySegment(arr); + } + + /** + * Creates a new array memory segment that models the memory associated with a given heap-allocated char array. + *
+ * The resulting memory segment keeps a reference to the backing array, to ensure it remains reachable + * for the life-time of the segment. + * + * @param arr the primitive array backing the array memory segment. + * @return a new array memory segment. + */ + static MemorySegment ofArray(char[] arr) { + return Utils.makeArraySegment(arr); + } + + /** + * Creates a new array memory segment that models the memory associated with a given heap-allocated short array. + *
+ * The resulting memory segment keeps a reference to the backing array, to ensure it remains reachable + * for the life-time of the segment. + * + * @param arr the primitive array backing the array memory segment. + * @return a new array memory segment. + */ + static MemorySegment ofArray(short[] arr) { + return Utils.makeArraySegment(arr); + } + + /** + * Creates a new array memory segment that models the memory associated with a given heap-allocated int array. + *
+ * The resulting memory segment keeps a reference to the backing array, to ensure it remains reachable + * for the life-time of the segment. + * + * @param arr the primitive array backing the array memory segment. + * @return a new array memory segment. + */ + static MemorySegment ofArray(int[] arr) { + return Utils.makeArraySegment(arr); + } + + /** + * Creates a new array memory segment that models the memory associated with a given heap-allocated float array. + *
+ * The resulting memory segment keeps a reference to the backing array, to ensure it remains reachable + * for the life-time of the segment. + * + * @param arr the primitive array backing the array memory segment. + * @return a new array memory segment. + */ + static MemorySegment ofArray(float[] arr) { + return Utils.makeArraySegment(arr); + } + + /** + * Creates a new array memory segment that models the memory associated with a given heap-allocated long array. + *
+ * The resulting memory segment keeps a reference to the backing array, to ensure it remains reachable + * for the life-time of the segment. + * + * @param arr the primitive array backing the array memory segment. + * @return a new array memory segment. + */ + static MemorySegment ofArray(long[] arr) { + return Utils.makeArraySegment(arr); + } + + /** + * Creates a new array memory segment that models the memory associated with a given heap-allocated double array. + *
+ * The resulting memory segment keeps a reference to the backing array, to ensure it remains reachable + * for the life-time of the segment. + * + * @param arr the primitive array backing the array memory segment. + * @return a new array memory segment. + */ + static MemorySegment ofArray(double[] arr) { + return Utils.makeArraySegment(arr); + } + + /** + * Creates a new native memory segment that models a newly allocated block of off-heap memory with given layout. + *
+ * This is equivalent to the following code: + *
{@code
+ allocateNative(layout.bytesSize(), layout.bytesAlignment());
+ * }+ * This is equivalent to the following code: + *
{@code
+ allocateNative(bytesSize, 1);
+ * }