14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 *
25 */
26
27 package jdk.incubator.foreign;
28
29 import java.nio.ByteBuffer;
30
31 import jdk.internal.foreign.AbstractMemorySegmentImpl;
32 import jdk.internal.foreign.HeapMemorySegmentImpl;
33 import jdk.internal.foreign.MappedMemorySegmentImpl;
34 import jdk.internal.foreign.NativeMemorySegmentImpl;
35 import jdk.internal.foreign.Utils;
36
37 import java.io.IOException;
38 import java.nio.channels.FileChannel;
39 import java.nio.file.Path;
40 import java.util.Objects;
41 import java.util.Spliterator;
42 import java.util.function.Consumer;
43
44 /**
45 * A memory segment models a contiguous region of memory. A memory segment is associated with both spatial
46 * and temporal bounds. Spatial bounds ensure that memory access operations on a memory segment cannot affect a memory location
47 * which falls <em>outside</em> the boundaries of the memory segment being accessed. Temporal checks ensure that memory access
48 * operations on a segment cannot occur after a memory segment has been closed (see {@link MemorySegment#close()}).
49 * <p>
50 * All implementations of this interface must be <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>;
51 * use of identity-sensitive operations (including reference equality ({@code ==}), identity hash code, or synchronization) on
52 * instances of {@code MemorySegment} may have unpredictable results and should be avoided. The {@code equals} method should
53 * be used for comparisons.
291 *
292 * <blockquote><pre>
293 * byteHandle = MemoryLayout.ofSequence(MemoryLayouts.JAVA_BYTE)
294 * .varHandle(byte.class, MemoryLayout.PathElement.sequenceElement());
295 * for (long l = 0; l < segment.byteSize(); l++) {
296 * byteHandle.set(segment.baseAddress(), l, value);
297 * }</pre></blockquote>
298 * without any regard or guarantees on the ordering of particular memory
299 * elements being set.
300 * <p>
301 * Fill can be useful to initialize or reset the memory of a segment.
302 *
303 * @param value the value to fill into this segment
304 * @return this memory segment
305 * @throws IllegalStateException if this segment is not <em>alive</em>, or if access occurs from a thread other than the
306 * thread owning this segment
307 * @throws UnsupportedOperationException if this segment does not support the {@link #WRITE} access mode
308 */
309 MemorySegment fill(byte value);
310
311 /**
312 * Wraps this segment in a {@link ByteBuffer}. Some of the properties of the returned buffer are linked to
313 * the properties of this segment. For instance, if this segment is <em>immutable</em>
314 * (e.g. the segment has access mode {@link #READ} but not {@link #WRITE}), then the resulting buffer is <em>read-only</em>
315 * (see {@link ByteBuffer#isReadOnly()}. Additionally, if this is a native memory segment, the resulting buffer is
316 * <em>direct</em> (see {@link ByteBuffer#isDirect()}).
317 * <p>
318 * The life-cycle of the returned buffer will be tied to that of this segment. That means that if the this segment
319 * is closed (see {@link MemorySegment#close()}, accessing the returned
320 * buffer will throw an {@link IllegalStateException}.
321 * <p>
322 * The resulting buffer's byte order is {@link java.nio.ByteOrder#BIG_ENDIAN}; this can be changed using
323 * {@link ByteBuffer#order(java.nio.ByteOrder)}.
324 *
325 * @return a {@link ByteBuffer} view of this memory segment.
326 * @throws UnsupportedOperationException if this segment cannot be mapped onto a {@link ByteBuffer} instance,
327 * e.g. because it models an heap-based segment that is not based on a {@code byte[]}), or if its size is greater
328 * than {@link Integer#MAX_VALUE}, or if the segment does not support the {@link #READ} access mode.
329 */
330 ByteBuffer asByteBuffer();
|
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 *
25 */
26
27 package jdk.incubator.foreign;
28
29 import java.nio.ByteBuffer;
30
31 import jdk.internal.foreign.AbstractMemorySegmentImpl;
32 import jdk.internal.foreign.HeapMemorySegmentImpl;
33 import jdk.internal.foreign.MappedMemorySegmentImpl;
34 import jdk.internal.foreign.MemoryAddressImpl;
35 import jdk.internal.foreign.NativeMemorySegmentImpl;
36 import jdk.internal.foreign.Utils;
37
38 import java.io.IOException;
39 import java.nio.channels.FileChannel;
40 import java.nio.file.Path;
41 import java.util.Objects;
42 import java.util.Spliterator;
43 import java.util.function.Consumer;
44
45 /**
46 * A memory segment models a contiguous region of memory. A memory segment is associated with both spatial
47 * and temporal bounds. Spatial bounds ensure that memory access operations on a memory segment cannot affect a memory location
48 * which falls <em>outside</em> the boundaries of the memory segment being accessed. Temporal checks ensure that memory access
49 * operations on a segment cannot occur after a memory segment has been closed (see {@link MemorySegment#close()}).
50 * <p>
51 * All implementations of this interface must be <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>;
52 * use of identity-sensitive operations (including reference equality ({@code ==}), identity hash code, or synchronization) on
53 * instances of {@code MemorySegment} may have unpredictable results and should be avoided. The {@code equals} method should
54 * be used for comparisons.
292 *
293 * <blockquote><pre>
294 * byteHandle = MemoryLayout.ofSequence(MemoryLayouts.JAVA_BYTE)
295 * .varHandle(byte.class, MemoryLayout.PathElement.sequenceElement());
296 * for (long l = 0; l < segment.byteSize(); l++) {
297 * byteHandle.set(segment.baseAddress(), l, value);
298 * }</pre></blockquote>
299 * without any regard or guarantees on the ordering of particular memory
300 * elements being set.
301 * <p>
302 * Fill can be useful to initialize or reset the memory of a segment.
303 *
304 * @param value the value to fill into this segment
305 * @return this memory segment
306 * @throws IllegalStateException if this segment is not <em>alive</em>, or if access occurs from a thread other than the
307 * thread owning this segment
308 * @throws UnsupportedOperationException if this segment does not support the {@link #WRITE} access mode
309 */
310 MemorySegment fill(byte value);
311
312 /**
313 * Perform bulk copy from given source segment to this segment. More specifically, the bytes at
314 * offset {@code 0} through {@code src.byteSize() - 1} in the source segment are copied into this segment
315 * at offset {@code 0} through {@code src.byteSize() - 1}.
316 * If the source segment overlaps with this segment, then the copying is performed as if the bytes at
317 * offset {@code 0} through {@code src.byteSize() - 1} in the source segment were first copied into a
318 * temporary segment with size {@code bytes}, and then the contents of the temporary segment were copied into
319 * this segment at offset {@code 0} through {@code src.byteSize() - 1}.
320 * <p>
321 * The result of a bulk copy is unspecified if, in the uncommon case, the source segment does not overlap with
322 * this segment, but it instead refers to an overlapping regions of the same backing storage using different addresses.
323 * For example, this may occur if the same file is {@link MemorySegment#mapFromPath mapped} to two segments.
324 *
325 * @param src the source segment.
326 * @throws IndexOutOfBoundsException if {src.byteSize() > this.byteSize()}.
327 * @throws IllegalStateException if either the source segment or this segment have been already closed,
328 * or if access occurs from a thread other than the thread owning either segment.
329 * @throws UnsupportedOperationException if either the source segment or this segment do not feature required access modes;
330 * more specifically, {@code src} should feature at least the {@link MemorySegment#READ} access mode,
331 * while this segment should feature at least the {@link MemorySegment#WRITE} access mode.
332 */
333 void copyFrom(MemorySegment src);
334
335 /**
336 * Wraps this segment in a {@link ByteBuffer}. Some of the properties of the returned buffer are linked to
337 * the properties of this segment. For instance, if this segment is <em>immutable</em>
338 * (e.g. the segment has access mode {@link #READ} but not {@link #WRITE}), then the resulting buffer is <em>read-only</em>
339 * (see {@link ByteBuffer#isReadOnly()}. Additionally, if this is a native memory segment, the resulting buffer is
340 * <em>direct</em> (see {@link ByteBuffer#isDirect()}).
341 * <p>
342 * The life-cycle of the returned buffer will be tied to that of this segment. That means that if the this segment
343 * is closed (see {@link MemorySegment#close()}, accessing the returned
344 * buffer will throw an {@link IllegalStateException}.
345 * <p>
346 * The resulting buffer's byte order is {@link java.nio.ByteOrder#BIG_ENDIAN}; this can be changed using
347 * {@link ByteBuffer#order(java.nio.ByteOrder)}.
348 *
349 * @return a {@link ByteBuffer} view of this memory segment.
350 * @throws UnsupportedOperationException if this segment cannot be mapped onto a {@link ByteBuffer} instance,
351 * e.g. because it models an heap-based segment that is not based on a {@code byte[]}), or if its size is greater
352 * than {@link Integer#MAX_VALUE}, or if the segment does not support the {@link #READ} access mode.
353 */
354 ByteBuffer asByteBuffer();
|