From 744f5b901222ab80950f14a9940b6aa93ca7905b Mon Sep 17 00:00:00 2001 From: Per Minborg Date: Mon, 24 Jul 2023 13:49:28 +0200 Subject: [PATCH 1/7] Update javadocs for SegmentAllocator::allocate methods --- .../java/lang/foreign/SegmentAllocator.java | 154 +++++++++++------- 1 file changed, 97 insertions(+), 57 deletions(-) diff --git a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java b/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java index 0c6133750e4e0..345cae964eeb0 100644 --- a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java +++ b/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java @@ -93,7 +93,7 @@ public interface SegmentAllocator { * @implSpec the default implementation for this method copies the contents of the provided Java string * into a new memory segment obtained by calling {@code this.allocate(str.length() + 1)}. * @param str the Java string to be converted into a C string. - * @return a new native segment containing the converted C string. + * @return a new segment containing the converted C string. */ default MemorySegment allocateUtf8String(String str) { Objects.requireNonNull(str); @@ -101,124 +101,164 @@ default MemorySegment allocateUtf8String(String str) { } /** - * Allocates a memory segment with the given layout and initializes it with the given byte value. - * @implSpec the default implementation for this method calls {@code this.allocate(layout)}. + * {@return a newly allocated memory segment with a {@link MemorySegment#byteSize()} of 1 + * initialized with the provided byte {@code value}}. + * + * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to + * allocate a segment after which the provided {@code value} is written into the segment using the + * byte ordering specified by the provided {@code layout}. + * * @param layout the layout of the block of memory to be allocated. - * @param value the value to be set on the newly allocated memory block. - * @return a segment for the newly allocated memory block. + * @param value the value to be set in the newly allocated memory segment. */ default MemorySegment allocate(ValueLayout.OfByte layout, byte value) { Objects.requireNonNull(layout); VarHandle handle = layout.varHandle(); - MemorySegment addr = allocate(layout); - handle.set(addr, value); - return addr; + MemorySegment seg = allocate(layout); + handle.set(seg, value); + return seg; } /** - * Allocates a memory segment with the given layout and initializes it with the given char value. - * @implSpec the default implementation for this method calls {@code this.allocate(layout)}. + * {@return a newly allocated memory segment with a {@link MemorySegment#byteSize()} of 2 + * initialized with the provided char {@code value} using the byte order of the provided + * {@link ValueLayout#order()} layout.order()}} + * + * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to + * allocate a segment after which the provided {@code value} is written into the segment using the + * byte ordering specified by the provided {@code layout}. + * * @param layout the layout of the block of memory to be allocated. - * @param value the value to be set on the newly allocated memory block. - * @return a segment for the newly allocated memory block. + * @param value the value to be set in the newly allocated memory segment. */ default MemorySegment allocate(ValueLayout.OfChar layout, char value) { Objects.requireNonNull(layout); VarHandle handle = layout.varHandle(); - MemorySegment addr = allocate(layout); - handle.set(addr, value); - return addr; + MemorySegment seg = allocate(layout); + handle.set(seg, value); + return seg; } /** - * Allocates a memory segment with the given layout and initializes it with the given short value. - * @implSpec the default implementation for this method calls {@code this.allocate(layout)}. + * {@return a newly allocated memory segment with a {@link MemorySegment#byteSize()} of 2 + * initialized with the provided short {@code value} using the byte order of the provided + * {@link ValueLayout#order()} layout.order()}} + * + * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to + * allocate a segment after which the provided {@code value} is written into the segment using the + * byte ordering specified by the provided {@code layout}. + * * @param layout the layout of the block of memory to be allocated. - * @param value the value to be set on the newly allocated memory block. - * @return a segment for the newly allocated memory block. + * @param value the value to be set in the newly allocated memory segment. */ default MemorySegment allocate(ValueLayout.OfShort layout, short value) { Objects.requireNonNull(layout); VarHandle handle = layout.varHandle(); - MemorySegment addr = allocate(layout); - handle.set(addr, value); - return addr; + MemorySegment seg = allocate(layout); + handle.set(seg, value); + return seg; } /** - * Allocates a memory segment with the given layout and initializes it with the given int value. - * @implSpec the default implementation for this method calls {@code this.allocate(layout)}. + * {@return a newly allocated memory segment with a {@link MemorySegment#byteSize()} of 4 + * initialized with the provided int {@code value} using the byte order of the provided + * {@link ValueLayout#order()} layout.order()}} + * + * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to + * allocate a segment after which the provided {@code value} is written into the segment using the + * byte ordering specified by the provided {@code layout}. + * * @param layout the layout of the block of memory to be allocated. - * @param value the value to be set on the newly allocated memory block. - * @return a segment for the newly allocated memory block. + * @param value the value to be set in the newly allocated memory segment. */ default MemorySegment allocate(ValueLayout.OfInt layout, int value) { Objects.requireNonNull(layout); VarHandle handle = layout.varHandle(); - MemorySegment addr = allocate(layout); - handle.set(addr, value); - return addr; + MemorySegment seg = allocate(layout); + handle.set(seg, value); + return seg; } /** - * Allocates a memory segment with the given layout and initializes it with the given float value. - * @implSpec the default implementation for this method calls {@code this.allocate(layout)}. + * {@return a newly allocated memory segment with a {@link MemorySegment#byteSize()} of 4 + * initialized with the provided float {@code value} using the byte order of the provided + * {@link ValueLayout#order()} layout.order()}} + * + * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to + * allocate a segment after which the provided {@code value} is written into the segment using the + * byte ordering specified by the provided {@code layout}. + * * @param layout the layout of the block of memory to be allocated. - * @param value the value to be set on the newly allocated memory block. - * @return a segment for the newly allocated memory block. + * @param value the value to be set in the newly allocated memory segment. */ default MemorySegment allocate(ValueLayout.OfFloat layout, float value) { Objects.requireNonNull(layout); VarHandle handle = layout.varHandle(); - MemorySegment addr = allocate(layout); - handle.set(addr, value); - return addr; + MemorySegment seg = allocate(layout); + handle.set(seg, value); + return seg; } /** - * Allocates a memory segment with the given layout and initializes it with the given long value. - * @implSpec the default implementation for this method calls {@code this.allocate(layout)}. + * {@return a newly allocated memory segment with a {@link MemorySegment#byteSize()} of 8 + * initialized with the provided long {@code value} using the byte order of the provided + * {@link ValueLayout#order()} layout.order()}} + * + * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to + * allocate a segment after which the provided {@code value} is written into the segment using the + * byte ordering specified by the provided {@code layout}. + * * @param layout the layout of the block of memory to be allocated. - * @param value the value to be set on the newly allocated memory block. - * @return a segment for the newly allocated memory block. + * @param value the value to be set in the newly allocated memory segment. */ default MemorySegment allocate(ValueLayout.OfLong layout, long value) { Objects.requireNonNull(layout); VarHandle handle = layout.varHandle(); - MemorySegment addr = allocate(layout); - handle.set(addr, value); - return addr; + MemorySegment seg = allocate(layout); + handle.set(seg, value); + return seg; } /** - * Allocates a memory segment with the given layout and initializes it with the given double value. - * @implSpec the default implementation for this method calls {@code this.allocate(layout)}. + * {@return a newly allocated memory segment with a {@link MemorySegment#byteSize()} of 8 + * initialized with the provided double {@code value} using the byte order of the provided + * {@link ValueLayout#order()} layout.order()}} + * + * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to + * allocate a segment after which the provided {@code value} is written into the segment using the + * byte ordering specified by the provided {@code layout}. + * * @param layout the layout of the block of memory to be allocated. - * @param value the value to be set on the newly allocated memory block. - * @return a segment for the newly allocated memory block. + * @param value the value to be set in the newly allocated memory segment. */ default MemorySegment allocate(ValueLayout.OfDouble layout, double value) { Objects.requireNonNull(layout); VarHandle handle = layout.varHandle(); - MemorySegment addr = allocate(layout); - handle.set(addr, value); - return addr; + MemorySegment seg = allocate(layout); + handle.set(seg, value); + return seg; } /** - * Allocates a memory segment with the given layout and initializes it with the given address value. + * {@return a newly allocated memory segment with a {@link MemorySegment#byteSize()} as specified by the + * provided {@link AddressLayout#byteSize() layout.byteSize()} initialized with the provided address {@code value} + * using the byte order of the provided {@link ValueLayout#order()} layout.order()}} + *

* The address value might be narrowed according to the platform address size (see {@link ValueLayout#ADDRESS}). - * @implSpec the default implementation for this method calls {@code this.allocate(layout)}. + * + * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to + * allocate a segment after which the provided {@code value} is written into the segment using the + * byte ordering specified by the provided {@code layout}. + * * @param layout the layout of the block of memory to be allocated. - * @param value the value to be set on the newly allocated memory block. - * @return a segment for the newly allocated memory block. + * @param value the value to be set in the newly allocated memory segment. */ default MemorySegment allocate(AddressLayout layout, MemorySegment value) { Objects.requireNonNull(value); Objects.requireNonNull(layout); - MemorySegment segment = allocate(layout); - layout.varHandle().set(segment, value); - return segment; + MemorySegment seg = allocate(layout); + layout.varHandle().set(seg, value); + return seg; } /** From 1154344d9cab94f3c74f641a243f864e8faf7dd5 Mon Sep 17 00:00:00 2001 From: Per Minborg Date: Mon, 24 Jul 2023 14:29:43 +0200 Subject: [PATCH 2/7] Improve javadocs --- .../java/lang/foreign/SegmentAllocator.java | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java b/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java index 345cae964eeb0..d76b458d3c9e7 100644 --- a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java +++ b/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java @@ -101,7 +101,7 @@ default MemorySegment allocateUtf8String(String str) { } /** - * {@return a newly allocated memory segment with a {@link MemorySegment#byteSize()} of 1 + * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of 1 * initialized with the provided byte {@code value}}. * * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to @@ -120,9 +120,9 @@ default MemorySegment allocate(ValueLayout.OfByte layout, byte value) { } /** - * {@return a newly allocated memory segment with a {@link MemorySegment#byteSize()} of 2 + * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of 2 * initialized with the provided char {@code value} using the byte order of the provided - * {@link ValueLayout#order()} layout.order()}} + * {@linkplain ValueLayout#order() layout.order()}} * * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to * allocate a segment after which the provided {@code value} is written into the segment using the @@ -140,9 +140,9 @@ default MemorySegment allocate(ValueLayout.OfChar layout, char value) { } /** - * {@return a newly allocated memory segment with a {@link MemorySegment#byteSize()} of 2 + * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of 2 * initialized with the provided short {@code value} using the byte order of the provided - * {@link ValueLayout#order()} layout.order()}} + * {@linkplain ValueLayout#order() layout.order()}} * * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to * allocate a segment after which the provided {@code value} is written into the segment using the @@ -160,9 +160,9 @@ default MemorySegment allocate(ValueLayout.OfShort layout, short value) { } /** - * {@return a newly allocated memory segment with a {@link MemorySegment#byteSize()} of 4 + * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of 4 * initialized with the provided int {@code value} using the byte order of the provided - * {@link ValueLayout#order()} layout.order()}} + * {@linkplain ValueLayout#order() layout.order()}} * * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to * allocate a segment after which the provided {@code value} is written into the segment using the @@ -180,9 +180,9 @@ default MemorySegment allocate(ValueLayout.OfInt layout, int value) { } /** - * {@return a newly allocated memory segment with a {@link MemorySegment#byteSize()} of 4 + * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of 4 * initialized with the provided float {@code value} using the byte order of the provided - * {@link ValueLayout#order()} layout.order()}} + * {@linkplain ValueLayout#order() layout.order()}} * * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to * allocate a segment after which the provided {@code value} is written into the segment using the @@ -200,9 +200,9 @@ default MemorySegment allocate(ValueLayout.OfFloat layout, float value) { } /** - * {@return a newly allocated memory segment with a {@link MemorySegment#byteSize()} of 8 + * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of 8 * initialized with the provided long {@code value} using the byte order of the provided - * {@link ValueLayout#order()} layout.order()}} + * {@linkplain ValueLayout#order() layout.order()}} * * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to * allocate a segment after which the provided {@code value} is written into the segment using the @@ -220,9 +220,9 @@ default MemorySegment allocate(ValueLayout.OfLong layout, long value) { } /** - * {@return a newly allocated memory segment with a {@link MemorySegment#byteSize()} of 8 + * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of 4 * initialized with the provided double {@code value} using the byte order of the provided - * {@link ValueLayout#order()} layout.order()}} + * {@linkplain ValueLayout#order() layout.order()}} * * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to * allocate a segment after which the provided {@code value} is written into the segment using the @@ -240,9 +240,9 @@ default MemorySegment allocate(ValueLayout.OfDouble layout, double value) { } /** - * {@return a newly allocated memory segment with a {@link MemorySegment#byteSize()} as specified by the - * provided {@link AddressLayout#byteSize() layout.byteSize()} initialized with the provided address {@code value} - * using the byte order of the provided {@link ValueLayout#order()} layout.order()}} + * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} as specified by the + * provided {@linkplain AddressLayout#byteSize() layout.byteSize()} initialized with the provided address {@code value} + * using the byte order of the provided {@link ValueLayout#order() layout.order()}} *

* The address value might be narrowed according to the platform address size (see {@link ValueLayout#ADDRESS}). * From e4d0a4bc12ded71638e44b3510b12c683d54815c Mon Sep 17 00:00:00 2001 From: Per Minborg Date: Mon, 24 Jul 2023 15:28:07 +0200 Subject: [PATCH 3/7] Update array methods --- .../java/lang/foreign/SegmentAllocator.java | 128 ++++++++++++------ 1 file changed, 85 insertions(+), 43 deletions(-) diff --git a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java b/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java index d76b458d3c9e7..e9b0180671f62 100644 --- a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java +++ b/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java @@ -90,7 +90,7 @@ public interface SegmentAllocator { * the string, such as {@link MemorySegment#getUtf8String(long)}, the string * will appear truncated when read again. * - * @implSpec the default implementation for this method copies the contents of the provided Java string + * @implSpec The default implementation for this method copies the contents of the provided Java string * into a new memory segment obtained by calling {@code this.allocate(str.length() + 1)}. * @param str the Java string to be converted into a C string. * @return a new segment containing the converted C string. @@ -104,7 +104,7 @@ default MemorySegment allocateUtf8String(String str) { * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of 1 * initialized with the provided byte {@code value}}. * - * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to + * @implSpec The default implementation of this method first calls {@code this.allocate(layout)} to * allocate a segment after which the provided {@code value} is written into the segment using the * byte ordering specified by the provided {@code layout}. * @@ -124,7 +124,7 @@ default MemorySegment allocate(ValueLayout.OfByte layout, byte value) { * initialized with the provided char {@code value} using the byte order of the provided * {@linkplain ValueLayout#order() layout.order()}} * - * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to + * @implSpec The default implementation of this method first calls {@code this.allocate(layout)} to * allocate a segment after which the provided {@code value} is written into the segment using the * byte ordering specified by the provided {@code layout}. * @@ -144,7 +144,7 @@ default MemorySegment allocate(ValueLayout.OfChar layout, char value) { * initialized with the provided short {@code value} using the byte order of the provided * {@linkplain ValueLayout#order() layout.order()}} * - * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to + * @implSpec The default implementation of this method first calls {@code this.allocate(layout)} to * allocate a segment after which the provided {@code value} is written into the segment using the * byte ordering specified by the provided {@code layout}. * @@ -164,7 +164,7 @@ default MemorySegment allocate(ValueLayout.OfShort layout, short value) { * initialized with the provided int {@code value} using the byte order of the provided * {@linkplain ValueLayout#order() layout.order()}} * - * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to + * @implSpec The default implementation of this method first calls {@code this.allocate(layout)} to * allocate a segment after which the provided {@code value} is written into the segment using the * byte ordering specified by the provided {@code layout}. * @@ -184,7 +184,7 @@ default MemorySegment allocate(ValueLayout.OfInt layout, int value) { * initialized with the provided float {@code value} using the byte order of the provided * {@linkplain ValueLayout#order() layout.order()}} * - * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to + * @implSpec The default implementation of this method first calls {@code this.allocate(layout)} to * allocate a segment after which the provided {@code value} is written into the segment using the * byte ordering specified by the provided {@code layout}. * @@ -204,7 +204,7 @@ default MemorySegment allocate(ValueLayout.OfFloat layout, float value) { * initialized with the provided long {@code value} using the byte order of the provided * {@linkplain ValueLayout#order() layout.order()}} * - * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to + * @implSpec The default implementation of this method first calls {@code this.allocate(layout)} to * allocate a segment after which the provided {@code value} is written into the segment using the * byte ordering specified by the provided {@code layout}. * @@ -224,7 +224,7 @@ default MemorySegment allocate(ValueLayout.OfLong layout, long value) { * initialized with the provided double {@code value} using the byte order of the provided * {@linkplain ValueLayout#order() layout.order()}} * - * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to + * @implSpec The default implementation of this method first calls {@code this.allocate(layout)} to * allocate a segment after which the provided {@code value} is written into the segment using the * byte ordering specified by the provided {@code layout}. * @@ -246,7 +246,7 @@ default MemorySegment allocate(ValueLayout.OfDouble layout, double value) { *

* The address value might be narrowed according to the platform address size (see {@link ValueLayout#ADDRESS}). * - * @implSpec the default implementation of this method first calls {@code this.allocate(layout)} to + * @implSpec The default implementation of this method first calls {@code this.allocate(layout)} to * allocate a segment after which the provided {@code value} is written into the segment using the * byte ordering specified by the provided {@code layout}. * @@ -262,77 +262,111 @@ default MemorySegment allocate(AddressLayout layout, MemorySegment value) { } /** - * Allocates a memory segment with the given layout and initializes it with the given byte elements. - * @implSpec the default implementation for this method calls {@code this.allocateArray(layout, array.length)}. + * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of + * {@code E} initialized with the provided {@code E} byte {@code elements}} + * + * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} + * to allocate a segment after which the provided {@code elements} are written into the segment using the + * byte ordering specified by the provided {@code layout}. + * * @param elementLayout the element layout of the array to be allocated. - * @param elements the byte elements to be copied to the newly allocated memory block. - * @return a segment for the newly allocated memory block. + * @param elements the short elements to be copied to the newly allocated memory block. */ default MemorySegment allocateArray(ValueLayout.OfByte elementLayout, byte... elements) { return copyArrayWithSwapIfNeeded(elements, elementLayout, MemorySegment::ofArray); } /** - * Allocates a memory segment with the given layout and initializes it with the given short elements. - * @implSpec the default implementation for this method calls {@code this.allocateArray(layout, array.length)}. + * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of + * {@code E*2} initialized with the provided {@code E} short {@code elements} using the byte order of + * the provided {@linkplain ValueLayout#order() layout.order()}} + * + * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} + * to allocate a segment after which the provided {@code elements} are written into the segment using the + * byte ordering specified by the provided {@code layout}. + * * @param elementLayout the element layout of the array to be allocated. - * @param elements the short elements to be copied to the newly allocated memory block. - * @return a segment for the newly allocated memory block. + * @param elements the short elements to be copied to the newly allocated memory block. */ default MemorySegment allocateArray(ValueLayout.OfShort elementLayout, short... elements) { return copyArrayWithSwapIfNeeded(elements, elementLayout, MemorySegment::ofArray); } /** - * Allocates a memory segment with the given layout and initializes it with the given char elements. - * @implSpec the default implementation for this method calls {@code this.allocateArray(layout, array.length)}. + * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of + * {@code E*2} initialized with the provided {@code E} char {@code elements} using the byte order of + * the provided {@linkplain ValueLayout#order() layout.order()}} + * + * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} + * to allocate a segment after which the provided {@code elements} are written into the segment using the + * byte ordering specified by the provided {@code layout}. + * * @param elementLayout the element layout of the array to be allocated. - * @param elements the char elements to be copied to the newly allocated memory block. - * @return a segment for the newly allocated memory block. + * @param elements the short elements to be copied to the newly allocated memory block. */ default MemorySegment allocateArray(ValueLayout.OfChar elementLayout, char... elements) { return copyArrayWithSwapIfNeeded(elements, elementLayout, MemorySegment::ofArray); } /** - * Allocates a memory segment with the given layout and initializes it with the given int elements. - * @implSpec the default implementation for this method calls {@code this.allocateArray(layout, array.length)}. + * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of + * {@code E*4} initialized with the provided {@code E} int {@code elements} using the byte order of + * the provided {@linkplain ValueLayout#order() layout.order()}} + * + * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} + * to allocate a segment after which the provided {@code elements} are written into the segment using the + * byte ordering specified by the provided {@code layout}. + * * @param elementLayout the element layout of the array to be allocated. - * @param elements the int elements to be copied to the newly allocated memory block. - * @return a segment for the newly allocated memory block. + * @param elements the short elements to be copied to the newly allocated memory block. */ default MemorySegment allocateArray(ValueLayout.OfInt elementLayout, int... elements) { return copyArrayWithSwapIfNeeded(elements, elementLayout, MemorySegment::ofArray); } /** - * Allocates a memory segment with the given layout and initializes it with the given float elements. - * @implSpec the default implementation for this method calls {@code this.allocateArray(layout, array.length)}. + * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of + * {@code E*4} initialized with the provided {@code E} float {@code elements} using the byte order of + * the provided {@linkplain ValueLayout#order() layout.order()}} + * + * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} + * to allocate a segment after which the provided {@code elements} are written into the segment using the + * byte ordering specified by the provided {@code layout}. + * * @param elementLayout the element layout of the array to be allocated. - * @param elements the float elements to be copied to the newly allocated memory block. - * @return a segment for the newly allocated memory block. + * @param elements the short elements to be copied to the newly allocated memory block. */ default MemorySegment allocateArray(ValueLayout.OfFloat elementLayout, float... elements) { return copyArrayWithSwapIfNeeded(elements, elementLayout, MemorySegment::ofArray); } /** - * Allocates a memory segment with the given layout and initializes it with the given long elements. - * @implSpec the default implementation for this method calls {@code this.allocateArray(layout, array.length)}. + * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of + * {@code E*8} initialized with the provided {@code E} long {@code elements} using the byte order of + * the provided {@linkplain ValueLayout#order() layout.order()}} + * + * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} + * to allocate a segment after which the provided {@code elements} are written into the segment using the + * byte ordering specified by the provided {@code layout}. + * * @param elementLayout the element layout of the array to be allocated. - * @param elements the long elements to be copied to the newly allocated memory block. - * @return a segment for the newly allocated memory block. + * @param elements the short elements to be copied to the newly allocated memory block. */ default MemorySegment allocateArray(ValueLayout.OfLong elementLayout, long... elements) { return copyArrayWithSwapIfNeeded(elements, elementLayout, MemorySegment::ofArray); } /** - * Allocates a memory segment with the given layout and initializes it with the given double elements. - * @implSpec the default implementation for this method calls {@code this.allocateArray(layout, array.length)}. + * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of + * {@code E*8} initialized with the provided {@code E} short {@code elements} using the byte order of + * the provided {@linkplain ValueLayout#order() layout.order()}} + * + * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} + * to allocate a segment after which the provided {@code elements} are written into the segment using the + * byte ordering specified by the provided {@code layout}. + * * @param elementLayout the element layout of the array to be allocated. - * @param elements the double elements to be copied to the newly allocated memory block. - * @return a segment for the newly allocated memory block. + * @param elements the short elements to be copied to the newly allocated memory block. */ default MemorySegment allocateArray(ValueLayout.OfDouble elementLayout, double... elements) { return copyArrayWithSwapIfNeeded(elements, elementLayout, MemorySegment::ofArray); @@ -341,17 +375,19 @@ default MemorySegment allocateArray(ValueLayout.OfDouble elementLayout, double.. private MemorySegment copyArrayWithSwapIfNeeded(Z array, ValueLayout elementLayout, Function heapSegmentFactory) { int size = Array.getLength(Objects.requireNonNull(array)); - MemorySegment addr = allocateArray(Objects.requireNonNull(elementLayout), size); + MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size); if (size > 0) { MemorySegment.copy(heapSegmentFactory.apply(array), elementLayout, 0, - addr, elementLayout.withOrder(ByteOrder.nativeOrder()), 0, size); + seg, elementLayout.withOrder(ByteOrder.nativeOrder()), 0, size); } - return addr; + return seg; } /** * Allocates a memory segment with the given layout. - * @implSpec the default implementation for this method calls {@code this.allocate(layout.byteSize(), layout.byteAlignment())}. + * + * @implSpec The default implementation for this method calls {@code this.allocate(layout.byteSize(), layout.byteAlignment())}. + * * @param layout the layout of the block of memory to be allocated. * @return a segment for the newly allocated memory block. */ @@ -362,7 +398,9 @@ default MemorySegment allocate(MemoryLayout layout) { /** * Allocates a memory segment with the given element layout and size. - * @implSpec the default implementation for this method calls {@code this.allocate(MemoryLayout.sequenceLayout(count, elementLayout))}. + * + * @implSpec The default implementation for this method calls {@code this.allocate(MemoryLayout.sequenceLayout(count, elementLayout))}. + * * @param elementLayout the array element layout. * @param count the array element count. * @return a segment for the newly allocated memory block. @@ -379,7 +417,9 @@ default MemorySegment allocateArray(MemoryLayout elementLayout, long count) { /** * Allocates a memory segment with the given size. - * @implSpec the default implementation for this method calls {@code this.allocate(byteSize, 1)}. + * + * @implSpec The default implementation for this method calls {@code this.allocate(byteSize, 1)}. + * * @param byteSize the size (in bytes) of the block of memory to be allocated. * @return a segment for the newly allocated memory block. * @throws IllegalArgumentException if {@code byteSize < 0} @@ -390,6 +430,7 @@ default MemorySegment allocate(long byteSize) { /** * Allocates a memory segment with the given size and alignment constraint. + * * @param byteSize the size (in bytes) of the block of memory to be allocated. * @param byteAlignment the alignment (in bytes) of the block of memory to be allocated. * @return a segment for the newly allocated memory block. @@ -405,6 +446,7 @@ default MemorySegment allocate(long byteSize) { *

* The returned allocator throws {@link IndexOutOfBoundsException} when a slice of the provided * segment with the requested size and alignment cannot be found. + * * @implNote A slicing allocator is not thread-safe. * * @param segment the segment which the returned allocator should slice from. From 66b1c8e5d82b027d31bd3e3b9a068c2d11c18369 Mon Sep 17 00:00:00 2001 From: Per Minborg Date: Wed, 26 Jul 2023 16:38:40 +0200 Subject: [PATCH 4/7] Update after comments --- .../java/lang/foreign/SegmentAllocator.java | 220 ++++++++++-------- 1 file changed, 127 insertions(+), 93 deletions(-) diff --git a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java b/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java index e9b0180671f62..3ba3b18500af7 100644 --- a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java +++ b/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java @@ -101,12 +101,17 @@ default MemorySegment allocateUtf8String(String str) { } /** - * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of 1 - * initialized with the provided byte {@code value}}. + * {@return a new memory segment initialized with the provided {@code byte} {@code value} as + * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * - * @implSpec The default implementation of this method first calls {@code this.allocate(layout)} to - * allocate a segment after which the provided {@code value} is written into the segment using the - * byte ordering specified by the provided {@code layout}. + * @implSpec The default implementation is equivalent to: + * {@snippet lang=java : + * Objects.requireNonNull(layout); + * VarHandle handle = layout.varHandle(); + * MemorySegment seg = allocate(layout); + * handle.set(seg, value); + * return seg; + * } * * @param layout the layout of the block of memory to be allocated. * @param value the value to be set in the newly allocated memory segment. @@ -120,13 +125,17 @@ default MemorySegment allocate(ValueLayout.OfByte layout, byte value) { } /** - * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of 2 - * initialized with the provided char {@code value} using the byte order of the provided - * {@linkplain ValueLayout#order() layout.order()}} + * {@return a new memory segment initialized with the provided {@code char} {@code value} as + * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * - * @implSpec The default implementation of this method first calls {@code this.allocate(layout)} to - * allocate a segment after which the provided {@code value} is written into the segment using the - * byte ordering specified by the provided {@code layout}. + * @implSpec The default implementation is equivalent to: + * {@snippet lang=java : + * Objects.requireNonNull(layout); + * VarHandle handle = layout.varHandle(); + * MemorySegment seg = allocate(layout); + * handle.set(seg, value); + * return seg; + * } * * @param layout the layout of the block of memory to be allocated. * @param value the value to be set in the newly allocated memory segment. @@ -140,13 +149,17 @@ default MemorySegment allocate(ValueLayout.OfChar layout, char value) { } /** - * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of 2 - * initialized with the provided short {@code value} using the byte order of the provided - * {@linkplain ValueLayout#order() layout.order()}} + * {@return a new memory segment initialized with the provided {@code short} {@code value} as + * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * - * @implSpec The default implementation of this method first calls {@code this.allocate(layout)} to - * allocate a segment after which the provided {@code value} is written into the segment using the - * byte ordering specified by the provided {@code layout}. + * @implSpec The default implementation is equivalent to: + * {@snippet lang=java : + * Objects.requireNonNull(layout); + * VarHandle handle = layout.varHandle(); + * MemorySegment seg = allocate(layout); + * handle.set(seg, value); + * return seg; + * } * * @param layout the layout of the block of memory to be allocated. * @param value the value to be set in the newly allocated memory segment. @@ -160,13 +173,17 @@ default MemorySegment allocate(ValueLayout.OfShort layout, short value) { } /** - * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of 4 - * initialized with the provided int {@code value} using the byte order of the provided - * {@linkplain ValueLayout#order() layout.order()}} + * {@return a new memory segment initialized with the provided {@code int} {@code value} as + * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * - * @implSpec The default implementation of this method first calls {@code this.allocate(layout)} to - * allocate a segment after which the provided {@code value} is written into the segment using the - * byte ordering specified by the provided {@code layout}. + * @implSpec The default implementation is equivalent to: + * {@snippet lang=java : + * Objects.requireNonNull(layout); + * VarHandle handle = layout.varHandle(); + * MemorySegment seg = allocate(layout); + * handle.set(seg, value); + * return seg; + * } * * @param layout the layout of the block of memory to be allocated. * @param value the value to be set in the newly allocated memory segment. @@ -180,13 +197,17 @@ default MemorySegment allocate(ValueLayout.OfInt layout, int value) { } /** - * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of 4 - * initialized with the provided float {@code value} using the byte order of the provided - * {@linkplain ValueLayout#order() layout.order()}} + * {@return a new memory segment initialized with the provided {@code float} {@code value} as + * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * - * @implSpec The default implementation of this method first calls {@code this.allocate(layout)} to - * allocate a segment after which the provided {@code value} is written into the segment using the - * byte ordering specified by the provided {@code layout}. + * @implSpec The default implementation is equivalent to: + * {@snippet lang=java : + * Objects.requireNonNull(layout); + * VarHandle handle = layout.varHandle(); + * MemorySegment seg = allocate(layout); + * handle.set(seg, value); + * return seg; + * } * * @param layout the layout of the block of memory to be allocated. * @param value the value to be set in the newly allocated memory segment. @@ -200,13 +221,17 @@ default MemorySegment allocate(ValueLayout.OfFloat layout, float value) { } /** - * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of 8 - * initialized with the provided long {@code value} using the byte order of the provided - * {@linkplain ValueLayout#order() layout.order()}} + * {@return a new memory segment initialized with the provided {@code long} {@code value} as + * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * - * @implSpec The default implementation of this method first calls {@code this.allocate(layout)} to - * allocate a segment after which the provided {@code value} is written into the segment using the - * byte ordering specified by the provided {@code layout}. + * @implSpec The default implementation is equivalent to: + * {@snippet lang=java : + * Objects.requireNonNull(layout); + * VarHandle handle = layout.varHandle(); + * MemorySegment seg = allocate(layout); + * handle.set(seg, value); + * return seg; + * } * * @param layout the layout of the block of memory to be allocated. * @param value the value to be set in the newly allocated memory segment. @@ -220,13 +245,17 @@ default MemorySegment allocate(ValueLayout.OfLong layout, long value) { } /** - * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of 4 - * initialized with the provided double {@code value} using the byte order of the provided - * {@linkplain ValueLayout#order() layout.order()}} + * {@return a new memory segment initialized with the provided {@code double} {@code value} as + * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * - * @implSpec The default implementation of this method first calls {@code this.allocate(layout)} to - * allocate a segment after which the provided {@code value} is written into the segment using the - * byte ordering specified by the provided {@code layout}. + * @implSpec The default implementation is equivalent to: + * {@snippet lang=java : + * Objects.requireNonNull(layout); + * VarHandle handle = layout.varHandle(); + * MemorySegment seg = allocate(layout); + * handle.set(seg, value); + * return seg; + * } * * @param layout the layout of the block of memory to be allocated. * @param value the value to be set in the newly allocated memory segment. @@ -240,15 +269,20 @@ default MemorySegment allocate(ValueLayout.OfDouble layout, double value) { } /** - * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} as specified by the - * provided {@linkplain AddressLayout#byteSize() layout.byteSize()} initialized with the provided address {@code value} - * using the byte order of the provided {@link ValueLayout#order() layout.order()}} + * {@return a new memory segment initialized with the address of the provided {@code value} as + * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} *

* The address value might be narrowed according to the platform address size (see {@link ValueLayout#ADDRESS}). * - * @implSpec The default implementation of this method first calls {@code this.allocate(layout)} to - * allocate a segment after which the provided {@code value} is written into the segment using the - * byte ordering specified by the provided {@code layout}. + * @implSpec The default implementation is equivalent to: + * {@snippet lang=java : + * Objects.requireNonNull(value); + * Objects.requireNonNull(layout); + * VarHandle handle = layout.varHandle(); + * MemorySegment seg = allocate(layout); + * handle.set(seg, value); + * return seg; + * } * * @param layout the layout of the block of memory to be allocated. * @param value the value to be set in the newly allocated memory segment. @@ -262,12 +296,13 @@ default MemorySegment allocate(AddressLayout layout, MemorySegment value) { } /** - * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of - * {@code E} initialized with the provided {@code E} byte {@code elements}} + * {@return a new memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of + * {@code E*layout.byteSize()} initialized with the provided {@code E} {@code byte} {@code elements} as + * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} - * to allocate a segment after which the provided {@code elements} are written into the segment using the - * byte ordering specified by the provided {@code layout}. + * to allocate a segment after which the provided {@code elements} are written into the segment as + * specified by the provided {@code layout}. * * @param elementLayout the element layout of the array to be allocated. * @param elements the short elements to be copied to the newly allocated memory block. @@ -277,13 +312,13 @@ default MemorySegment allocateArray(ValueLayout.OfByte elementLayout, byte... el } /** - * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of - * {@code E*2} initialized with the provided {@code E} short {@code elements} using the byte order of - * the provided {@linkplain ValueLayout#order() layout.order()}} + * {@return a new memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of + * {@code E*layout.byteSize()} initialized with the provided {@code E} {@code short} {@code elements} as + * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} - * to allocate a segment after which the provided {@code elements} are written into the segment using the - * byte ordering specified by the provided {@code layout}. + * to allocate a segment after which the provided {@code elements} are written into the segment as + * specified by the provided {@code layout}. * * @param elementLayout the element layout of the array to be allocated. * @param elements the short elements to be copied to the newly allocated memory block. @@ -293,13 +328,13 @@ default MemorySegment allocateArray(ValueLayout.OfShort elementLayout, short... } /** - * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of - * {@code E*2} initialized with the provided {@code E} char {@code elements} using the byte order of - * the provided {@linkplain ValueLayout#order() layout.order()}} + * {@return a new memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of + * {@code E*layout.byteSize()} initialized with the provided {@code E} {@code char} {@code elements} as + * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} - * to allocate a segment after which the provided {@code elements} are written into the segment using the - * byte ordering specified by the provided {@code layout}. + * to allocate a segment after which the provided {@code elements} are written into the segment as + * specified by the provided {@code layout}. * * @param elementLayout the element layout of the array to be allocated. * @param elements the short elements to be copied to the newly allocated memory block. @@ -309,13 +344,13 @@ default MemorySegment allocateArray(ValueLayout.OfChar elementLayout, char... el } /** - * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of - * {@code E*4} initialized with the provided {@code E} int {@code elements} using the byte order of - * the provided {@linkplain ValueLayout#order() layout.order()}} + * {@return a new memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of + * {@code E*layout.byteSize()} initialized with the provided {@code E} {@code int} {@code elements} as + * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} - * to allocate a segment after which the provided {@code elements} are written into the segment using the - * byte ordering specified by the provided {@code layout}. + * to allocate a segment after which the provided {@code elements} are written into the segment as + * specified by the provided {@code layout}. * * @param elementLayout the element layout of the array to be allocated. * @param elements the short elements to be copied to the newly allocated memory block. @@ -325,13 +360,13 @@ default MemorySegment allocateArray(ValueLayout.OfInt elementLayout, int... elem } /** - * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of - * {@code E*4} initialized with the provided {@code E} float {@code elements} using the byte order of - * the provided {@linkplain ValueLayout#order() layout.order()}} + * {@return a new memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of + * {@code E*layout.byteSize()} initialized with the provided {@code E} {@code float} {@code elements} as + * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} - * to allocate a segment after which the provided {@code elements} are written into the segment using the - * byte ordering specified by the provided {@code layout}. + * to allocate a segment after which the provided {@code elements} are written into the segment as + * specified by the provided {@code layout}. * * @param elementLayout the element layout of the array to be allocated. * @param elements the short elements to be copied to the newly allocated memory block. @@ -341,13 +376,13 @@ default MemorySegment allocateArray(ValueLayout.OfFloat elementLayout, float... } /** - * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of - * {@code E*8} initialized with the provided {@code E} long {@code elements} using the byte order of - * the provided {@linkplain ValueLayout#order() layout.order()}} + * {@return a new memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of + * {@code E*layout.byteSize()} initialized with the provided {@code E} {@code long} {@code elements} as + * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} - * to allocate a segment after which the provided {@code elements} are written into the segment using the - * byte ordering specified by the provided {@code layout}. + * to allocate a segment after which the provided {@code elements} are written into the segment as + * specified by the provided {@code layout}. * * @param elementLayout the element layout of the array to be allocated. * @param elements the short elements to be copied to the newly allocated memory block. @@ -357,13 +392,13 @@ default MemorySegment allocateArray(ValueLayout.OfLong elementLayout, long... el } /** - * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of - * {@code E*8} initialized with the provided {@code E} short {@code elements} using the byte order of - * the provided {@linkplain ValueLayout#order() layout.order()}} + * {@return a new memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of + * {@code E*layout.byteSize()} initialized with the provided {@code E} {@code double} {@code elements} as + * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} - * to allocate a segment after which the provided {@code elements} are written into the segment using the - * byte ordering specified by the provided {@code layout}. + * to allocate a segment after which the provided {@code elements} are written into the segment as + * specified by the provided {@code layout}. * * @param elementLayout the element layout of the array to be allocated. * @param elements the short elements to be copied to the newly allocated memory block. @@ -384,12 +419,12 @@ private MemorySegment copyArrayWithSwapIfNeeded(Z array, ValueLayout element } /** - * Allocates a memory segment with the given layout. + * {@return a new memory segment with the given layout} * - * @implSpec The default implementation for this method calls {@code this.allocate(layout.byteSize(), layout.byteAlignment())}. + * @implSpec The default implementation for this method calls + * {@code this.allocate(layout.byteSize(), layout.byteAlignment())}. * * @param layout the layout of the block of memory to be allocated. - * @return a segment for the newly allocated memory block. */ default MemorySegment allocate(MemoryLayout layout) { Objects.requireNonNull(layout); @@ -397,13 +432,13 @@ default MemorySegment allocate(MemoryLayout layout) { } /** - * Allocates a memory segment with the given element layout and size. + * {@return a new memory segment with the given {@code elementLayout} and {@code count}} * - * @implSpec The default implementation for this method calls {@code this.allocate(MemoryLayout.sequenceLayout(count, elementLayout))}. + * @implSpec The default implementation for this method calls + * {@code this.allocate(MemoryLayout.sequenceLayout(count, elementLayout))}. * * @param elementLayout the array element layout. * @param count the array element count. - * @return a segment for the newly allocated memory block. * @throws IllegalArgumentException if {@code elementLayout.byteSize() * count} overflows. * @throws IllegalArgumentException if {@code count < 0}. */ @@ -416,12 +451,12 @@ default MemorySegment allocateArray(MemoryLayout elementLayout, long count) { } /** - * Allocates a memory segment with the given size. + * {@return a new memory segment with the given {@code byteSize}} * - * @implSpec The default implementation for this method calls {@code this.allocate(byteSize, 1)}. + * @implSpec The default implementation for this method calls + * {@code this.allocate(byteSize, 1)}. * * @param byteSize the size (in bytes) of the block of memory to be allocated. - * @return a segment for the newly allocated memory block. * @throws IllegalArgumentException if {@code byteSize < 0} */ default MemorySegment allocate(long byteSize) { @@ -429,13 +464,12 @@ default MemorySegment allocate(long byteSize) { } /** - * Allocates a memory segment with the given size and alignment constraint. + * {@return a new memory segment with the given {@code byteSize} and {@code byteAlignment}} * * @param byteSize the size (in bytes) of the block of memory to be allocated. * @param byteAlignment the alignment (in bytes) of the block of memory to be allocated. - * @return a segment for the newly allocated memory block. * @throws IllegalArgumentException if {@code byteSize < 0}, {@code byteAlignment <= 0}, - * or if {@code byteAlignment} is not a power of 2. + * or if {@code byteAlignment} is not a power of 2. */ MemorySegment allocate(long byteSize, long byteAlignment); From 46951bdd6cf38c6e24fb1ca48610ea84498ed03d Mon Sep 17 00:00:00 2001 From: Per Minborg Date: Tue, 8 Aug 2023 10:18:16 +0200 Subject: [PATCH 5/7] Simplify snippets --- .../java/lang/foreign/SegmentAllocator.java | 50 +++++++------------ 1 file changed, 17 insertions(+), 33 deletions(-) diff --git a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java b/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java index 3ba3b18500af7..61a194c84c429 100644 --- a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java +++ b/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java @@ -106,10 +106,8 @@ default MemorySegment allocateUtf8String(String str) { * * @implSpec The default implementation is equivalent to: * {@snippet lang=java : - * Objects.requireNonNull(layout); - * VarHandle handle = layout.varHandle(); - * MemorySegment seg = allocate(layout); - * handle.set(seg, value); + * MemorySegment seg = allocate(Objects.requireNonNull(layout)); + * seg.set(layout, 0, value); * return seg; * } * @@ -130,10 +128,8 @@ default MemorySegment allocate(ValueLayout.OfByte layout, byte value) { * * @implSpec The default implementation is equivalent to: * {@snippet lang=java : - * Objects.requireNonNull(layout); - * VarHandle handle = layout.varHandle(); - * MemorySegment seg = allocate(layout); - * handle.set(seg, value); + * MemorySegment seg = allocate(Objects.requireNonNull(layout)); + * seg.set(layout, 0, value); * return seg; * } * @@ -154,10 +150,8 @@ default MemorySegment allocate(ValueLayout.OfChar layout, char value) { * * @implSpec The default implementation is equivalent to: * {@snippet lang=java : - * Objects.requireNonNull(layout); - * VarHandle handle = layout.varHandle(); - * MemorySegment seg = allocate(layout); - * handle.set(seg, value); + * MemorySegment seg = allocate(Objects.requireNonNull(layout)); + * seg.set(layout, 0, value); * return seg; * } * @@ -178,10 +172,8 @@ default MemorySegment allocate(ValueLayout.OfShort layout, short value) { * * @implSpec The default implementation is equivalent to: * {@snippet lang=java : - * Objects.requireNonNull(layout); - * VarHandle handle = layout.varHandle(); - * MemorySegment seg = allocate(layout); - * handle.set(seg, value); + * MemorySegment seg = allocate(Objects.requireNonNull(layout)); + * seg.set(layout, 0, value); * return seg; * } * @@ -202,10 +194,8 @@ default MemorySegment allocate(ValueLayout.OfInt layout, int value) { * * @implSpec The default implementation is equivalent to: * {@snippet lang=java : - * Objects.requireNonNull(layout); - * VarHandle handle = layout.varHandle(); - * MemorySegment seg = allocate(layout); - * handle.set(seg, value); + * MemorySegment seg = allocate(Objects.requireNonNull(layout)); + * seg.set(layout, 0, value); * return seg; * } * @@ -226,10 +216,8 @@ default MemorySegment allocate(ValueLayout.OfFloat layout, float value) { * * @implSpec The default implementation is equivalent to: * {@snippet lang=java : - * Objects.requireNonNull(layout); - * VarHandle handle = layout.varHandle(); - * MemorySegment seg = allocate(layout); - * handle.set(seg, value); + * MemorySegment seg = allocate(Objects.requireNonNull(layout)); + * seg.set(layout, 0, value); * return seg; * } * @@ -250,10 +238,8 @@ default MemorySegment allocate(ValueLayout.OfLong layout, long value) { * * @implSpec The default implementation is equivalent to: * {@snippet lang=java : - * Objects.requireNonNull(layout); - * VarHandle handle = layout.varHandle(); - * MemorySegment seg = allocate(layout); - * handle.set(seg, value); + * MemorySegment seg = allocate(Objects.requireNonNull(layout)); + * seg.set(layout, 0, value); * return seg; * } * @@ -277,10 +263,8 @@ default MemorySegment allocate(ValueLayout.OfDouble layout, double value) { * @implSpec The default implementation is equivalent to: * {@snippet lang=java : * Objects.requireNonNull(value); - * Objects.requireNonNull(layout); - * VarHandle handle = layout.varHandle(); - * MemorySegment seg = allocate(layout); - * handle.set(seg, value); + * MemorySegment seg = allocate(Objects.requireNonNull(layout)); + * seg.set(layout, 0, value); * return seg; * } * @@ -469,7 +453,7 @@ default MemorySegment allocate(long byteSize) { * @param byteSize the size (in bytes) of the block of memory to be allocated. * @param byteAlignment the alignment (in bytes) of the block of memory to be allocated. * @throws IllegalArgumentException if {@code byteSize < 0}, {@code byteAlignment <= 0}, - * or if {@code byteAlignment} is not a power of 2. + * or if {@code byteAlignment} is not a power of 2. */ MemorySegment allocate(long byteSize, long byteAlignment); From c7544307c68ca6f74f453f732e68fd23bce17d6b Mon Sep 17 00:00:00 2001 From: Per Minborg Date: Tue, 8 Aug 2023 10:30:35 +0200 Subject: [PATCH 6/7] Add snippet for MS::allocateArray methods --- .../java/lang/foreign/SegmentAllocator.java | 81 +++++++++++++------ 1 file changed, 57 insertions(+), 24 deletions(-) diff --git a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java b/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java index 61a194c84c429..72d4934f945ae 100644 --- a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java +++ b/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java @@ -77,8 +77,7 @@ public interface SegmentAllocator { /** - * Converts a Java string into a UTF-8 encoded, null-terminated C string, - * storing the result into a memory segment. + * {@return a new memory segment with a Java string converted into a UTF-8 encoded, null-terminated C string} *

* This method always replaces malformed-input and unmappable-character * sequences with this charset's default replacement byte array. The @@ -93,7 +92,6 @@ public interface SegmentAllocator { * @implSpec The default implementation for this method copies the contents of the provided Java string * into a new memory segment obtained by calling {@code this.allocate(str.length() + 1)}. * @param str the Java string to be converted into a C string. - * @return a new segment containing the converted C string. */ default MemorySegment allocateUtf8String(String str) { Objects.requireNonNull(str); @@ -284,9 +282,14 @@ default MemorySegment allocate(AddressLayout layout, MemorySegment value) { * {@code E*layout.byteSize()} initialized with the provided {@code E} {@code byte} {@code elements} as * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * - * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} - * to allocate a segment after which the provided {@code elements} are written into the segment as - * specified by the provided {@code layout}. + * @implSpec The default implementation is equivalent to: + * {@snippet lang=java : + * int size = Objects.requireNonNull(elements).length; + * MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size); + * MemorySegment.copy(MemorySegment.ofArray(elements), elementLayout, 0, + * seg, elementLayout.withOrder(ByteOrder.nativeOrder()), 0, size); + * return seg; + * } * * @param elementLayout the element layout of the array to be allocated. * @param elements the short elements to be copied to the newly allocated memory block. @@ -300,9 +303,14 @@ default MemorySegment allocateArray(ValueLayout.OfByte elementLayout, byte... el * {@code E*layout.byteSize()} initialized with the provided {@code E} {@code short} {@code elements} as * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * - * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} - * to allocate a segment after which the provided {@code elements} are written into the segment as - * specified by the provided {@code layout}. + * @implSpec The default implementation is equivalent to: + * {@snippet lang=java : + * int size = Objects.requireNonNull(elements).length; + * MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size); + * MemorySegment.copy(MemorySegment.ofArray(elements), elementLayout, 0, + * seg, elementLayout.withOrder(ByteOrder.nativeOrder()), 0, size); + * return seg; + * } * * @param elementLayout the element layout of the array to be allocated. * @param elements the short elements to be copied to the newly allocated memory block. @@ -316,9 +324,14 @@ default MemorySegment allocateArray(ValueLayout.OfShort elementLayout, short... * {@code E*layout.byteSize()} initialized with the provided {@code E} {@code char} {@code elements} as * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * - * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} - * to allocate a segment after which the provided {@code elements} are written into the segment as - * specified by the provided {@code layout}. + * @implSpec The default implementation is equivalent to: + * {@snippet lang=java : + * int size = Objects.requireNonNull(elements).length; + * MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size); + * MemorySegment.copy(MemorySegment.ofArray(elements), elementLayout, 0, + * seg, elementLayout.withOrder(ByteOrder.nativeOrder()), 0, size); + * return seg; + * } * * @param elementLayout the element layout of the array to be allocated. * @param elements the short elements to be copied to the newly allocated memory block. @@ -332,9 +345,14 @@ default MemorySegment allocateArray(ValueLayout.OfChar elementLayout, char... el * {@code E*layout.byteSize()} initialized with the provided {@code E} {@code int} {@code elements} as * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * - * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} - * to allocate a segment after which the provided {@code elements} are written into the segment as - * specified by the provided {@code layout}. + * @implSpec The default implementation is equivalent to: + * {@snippet lang=java : + * int size = Objects.requireNonNull(elements).length; + * MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size); + * MemorySegment.copy(MemorySegment.ofArray(elements), elementLayout, 0, + * seg, elementLayout.withOrder(ByteOrder.nativeOrder()), 0, size); + * return seg; + * } * * @param elementLayout the element layout of the array to be allocated. * @param elements the short elements to be copied to the newly allocated memory block. @@ -348,9 +366,14 @@ default MemorySegment allocateArray(ValueLayout.OfInt elementLayout, int... elem * {@code E*layout.byteSize()} initialized with the provided {@code E} {@code float} {@code elements} as * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * - * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} - * to allocate a segment after which the provided {@code elements} are written into the segment as - * specified by the provided {@code layout}. + * @implSpec The default implementation is equivalent to: + * {@snippet lang=java : + * int size = Objects.requireNonNull(elements).length; + * MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size); + * MemorySegment.copy(MemorySegment.ofArray(elements), elementLayout, 0, + * seg, elementLayout.withOrder(ByteOrder.nativeOrder()), 0, size); + * return seg; + * } * * @param elementLayout the element layout of the array to be allocated. * @param elements the short elements to be copied to the newly allocated memory block. @@ -364,9 +387,14 @@ default MemorySegment allocateArray(ValueLayout.OfFloat elementLayout, float... * {@code E*layout.byteSize()} initialized with the provided {@code E} {@code long} {@code elements} as * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * - * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} - * to allocate a segment after which the provided {@code elements} are written into the segment as - * specified by the provided {@code layout}. + * @implSpec The default implementation is equivalent to: + * {@snippet lang=java : + * int size = Objects.requireNonNull(elements).length; + * MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size); + * MemorySegment.copy(MemorySegment.ofArray(elements), elementLayout, 0, + * seg, elementLayout.withOrder(ByteOrder.nativeOrder()), 0, size); + * return seg; + * } * * @param elementLayout the element layout of the array to be allocated. * @param elements the short elements to be copied to the newly allocated memory block. @@ -380,9 +408,14 @@ default MemorySegment allocateArray(ValueLayout.OfLong elementLayout, long... el * {@code E*layout.byteSize()} initialized with the provided {@code E} {@code double} {@code elements} as * specified by the provided {@code layout} (i.e. byte ordering, alignment and size)} * - * @implSpec The default implementation of this method first calls {@code this.allocateArray(layout, array.length)} - * to allocate a segment after which the provided {@code elements} are written into the segment as - * specified by the provided {@code layout}. + * @implSpec The default implementation is equivalent to: + * {@snippet lang=java : + * int size = Objects.requireNonNull(elements).length; + * MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size); + * MemorySegment.copy(MemorySegment.ofArray(elements), elementLayout, 0, + * seg, elementLayout.withOrder(ByteOrder.nativeOrder()), 0, size); + * return seg; + * } * * @param elementLayout the element layout of the array to be allocated. * @param elements the short elements to be copied to the newly allocated memory block. From f0f80b85e0beb6c7d8fc4a02c92401671efa2756 Mon Sep 17 00:00:00 2001 From: Per Minborg Date: Thu, 10 Aug 2023 09:54:55 +0200 Subject: [PATCH 7/7] Simplify java snippets --- .../java/lang/foreign/SegmentAllocator.java | 21 +++++++------------ 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java b/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java index 72d4934f945ae..b659e32fa8a2f 100644 --- a/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java +++ b/src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java @@ -286,8 +286,7 @@ default MemorySegment allocate(AddressLayout layout, MemorySegment value) { * {@snippet lang=java : * int size = Objects.requireNonNull(elements).length; * MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size); - * MemorySegment.copy(MemorySegment.ofArray(elements), elementLayout, 0, - * seg, elementLayout.withOrder(ByteOrder.nativeOrder()), 0, size); + * MemorySegment.copy(elements, 0, seg, elementLayout, 0, size); * return seg; * } * @@ -307,8 +306,7 @@ default MemorySegment allocateArray(ValueLayout.OfByte elementLayout, byte... el * {@snippet lang=java : * int size = Objects.requireNonNull(elements).length; * MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size); - * MemorySegment.copy(MemorySegment.ofArray(elements), elementLayout, 0, - * seg, elementLayout.withOrder(ByteOrder.nativeOrder()), 0, size); + * MemorySegment.copy(elements, 0, seg, elementLayout, 0, size); * return seg; * } * @@ -328,8 +326,7 @@ default MemorySegment allocateArray(ValueLayout.OfShort elementLayout, short... * {@snippet lang=java : * int size = Objects.requireNonNull(elements).length; * MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size); - * MemorySegment.copy(MemorySegment.ofArray(elements), elementLayout, 0, - * seg, elementLayout.withOrder(ByteOrder.nativeOrder()), 0, size); + * MemorySegment.copy(elements, 0, seg, elementLayout, 0, size); * return seg; * } * @@ -349,8 +346,7 @@ default MemorySegment allocateArray(ValueLayout.OfChar elementLayout, char... el * {@snippet lang=java : * int size = Objects.requireNonNull(elements).length; * MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size); - * MemorySegment.copy(MemorySegment.ofArray(elements), elementLayout, 0, - * seg, elementLayout.withOrder(ByteOrder.nativeOrder()), 0, size); + * MemorySegment.copy(elements, 0, seg, elementLayout, 0, size); * return seg; * } * @@ -370,8 +366,7 @@ default MemorySegment allocateArray(ValueLayout.OfInt elementLayout, int... elem * {@snippet lang=java : * int size = Objects.requireNonNull(elements).length; * MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size); - * MemorySegment.copy(MemorySegment.ofArray(elements), elementLayout, 0, - * seg, elementLayout.withOrder(ByteOrder.nativeOrder()), 0, size); + * MemorySegment.copy(elements, 0, seg, elementLayout, 0, size); * return seg; * } * @@ -391,8 +386,7 @@ default MemorySegment allocateArray(ValueLayout.OfFloat elementLayout, float... * {@snippet lang=java : * int size = Objects.requireNonNull(elements).length; * MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size); - * MemorySegment.copy(MemorySegment.ofArray(elements), elementLayout, 0, - * seg, elementLayout.withOrder(ByteOrder.nativeOrder()), 0, size); + * MemorySegment.copy(elements, 0, seg, elementLayout, 0, size); * return seg; * } * @@ -412,8 +406,7 @@ default MemorySegment allocateArray(ValueLayout.OfLong elementLayout, long... el * {@snippet lang=java : * int size = Objects.requireNonNull(elements).length; * MemorySegment seg = allocateArray(Objects.requireNonNull(elementLayout), size); - * MemorySegment.copy(MemorySegment.ofArray(elements), elementLayout, 0, - * seg, elementLayout.withOrder(ByteOrder.nativeOrder()), 0, size); + * MemorySegment.copy(elements, 0, seg, elementLayout, 0, size); * return seg; * } *