Skip to content
Permalink
Browse files
8264434: Remove ResourceScope-less overload from API
Reviewed-by: psandoz, jvernee
  • Loading branch information
mcimadamore committed Mar 30, 2021
1 parent ab46878 commit a4ba76c32d55bc81add386b85d95e8ca37d37782
Showing with 172 additions and 423 deletions.
  1. +1 −93 src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/CLinker.java
  2. +0 −26 src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryAddress.java
  3. +4 −95 src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java
  4. +25 −42 src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ResourceScope.java
  5. +7 −8 src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/SegmentAllocator.java
  6. +4 −4 src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java
  7. +0 −6 src/jdk.incubator.foreign/share/classes/jdk/internal/foreign/AbstractCLinker.java
  8. +2 −2 src/jdk.incubator.foreign/share/classes/jdk/internal/foreign/ConfinedScope.java
  9. +1 −1 src/jdk.incubator.foreign/share/classes/jdk/internal/foreign/LibrariesHelper.java
  10. +0 −7 src/jdk.incubator.foreign/share/classes/jdk/internal/foreign/MemoryAddressImpl.java
  11. +22 −16 src/jdk.incubator.foreign/share/classes/jdk/internal/foreign/MemoryScope.java
  12. +2 −1 src/jdk.incubator.foreign/share/classes/jdk/internal/foreign/NativeMemorySegmentImpl.java
  13. +2 −2 src/jdk.incubator.foreign/share/classes/jdk/internal/foreign/SharedScope.java
  14. +3 −9 src/jdk.incubator.foreign/share/classes/jdk/internal/foreign/abi/Binding.java
  15. +2 −9 src/jdk.incubator.foreign/share/classes/jdk/internal/foreign/abi/SharedUtils.java
  16. +2 −3 src/jdk.incubator.foreign/share/classes/jdk/internal/foreign/abi/aarch64/AArch64Linker.java
  17. +2 −6 src/jdk.incubator.foreign/share/classes/jdk/internal/foreign/abi/aarch64/AArch64VaList.java
  18. +2 −6 src/jdk.incubator.foreign/share/classes/jdk/internal/foreign/abi/x64/sysv/SysVVaList.java
  19. +2 −3 src/jdk.incubator.foreign/share/classes/jdk/internal/foreign/abi/x64/sysv/SysVx64Linker.java
  20. +1 −6 src/jdk.incubator.foreign/share/classes/jdk/internal/foreign/abi/x64/windows/WinVaList.java
  21. +2 −3 src/jdk.incubator.foreign/share/classes/jdk/internal/foreign/abi/x64/windows/Windowsx64Linker.java
  22. +4 −3 test/jdk/java/foreign/CallGeneratorHelper.java
  23. +1 −1 test/jdk/java/foreign/StdLibTest.java
  24. +9 −8 test/jdk/java/foreign/TestAdaptVarHandles.java
  25. +2 −2 test/jdk/java/foreign/TestArrays.java
  26. +6 −6 test/jdk/java/foreign/TestByteBuffer.java
  27. +1 −1 test/jdk/java/foreign/TestDowncall.java
  28. +3 −1 test/jdk/java/foreign/TestFree.java
  29. +2 −1 test/jdk/java/foreign/TestMemoryCopy.java
  30. +1 −1 test/jdk/java/foreign/TestMismatch.java
  31. +1 −1 test/jdk/java/foreign/TestNative.java
  32. +3 −7 test/jdk/java/foreign/TestNulls.java
  33. +2 −1 test/jdk/java/foreign/TestRebase.java
  34. +15 −5 test/jdk/java/foreign/TestResourceScope.java
  35. +6 −5 test/jdk/java/foreign/TestRestricted.java
  36. +1 −1 test/jdk/java/foreign/TestScopedOperations.java
  37. +8 −10 test/jdk/java/foreign/TestSegments.java
  38. +1 −1 test/jdk/java/foreign/TestSpliterator.java
  39. +4 −4 test/jdk/java/foreign/TestUpcall.java
  40. +1 −1 test/jdk/java/foreign/TestUpcallHighArity.java
  41. +1 −1 test/jdk/java/foreign/TestVarHandleCombinators.java
  42. +14 −14 test/jdk/java/foreign/valist/VaListTest.java
@@ -202,22 +202,6 @@ static CLinker getInstance() {
@NativeAccess
MemorySegment upcallStub(MethodHandle target, FunctionDescriptor function, ResourceScope scope);

/**
* Allocates a native segment which can be passed to other foreign functions (as a function pointer);
* calling such a function pointer from native code will result in the execution of the provided method handle.
* <p>
* The returned segment is associated with a fresh, shared, resource scope,
* which will be automatically closed when the segment (or views derived from it) is no longer in use.
* The scope associated with the returned segment cannot be closed directly e.g. by calling {@link ResourceScope#close()}.
*
* @param target the target method handle.
* @param function the function descriptor.
* @return the native stub segment.
* @throws IllegalArgumentException if the target's method type and the function descriptor mismatch.
*/
@NativeAccess
MemorySegment upcallStub(MethodHandle target, FunctionDescriptor function);

/**
* The layout for the {@code char} C type
*/
@@ -268,43 +252,6 @@ static CLinker getInstance() {
return (T) PlatformLayouts.asVarArg(layout);
}

/**
* Converts a Java string into a null-terminated C string, using the
* platform's default charset, storing the result into a new native memory segment, associated with
* a fresh {@link ResourceScope#ofDefault() default scope}.
* <p>
* This method always replaces malformed-input and unmappable-character
* sequences with this charset's default replacement byte array. The
* {@link java.nio.charset.CharsetEncoder} class should be used when more
* control over the encoding process is required.
*
* @param str the Java string to be converted into a C string.
* @return a new native memory segment containing the converted C string.
*/
static MemorySegment toCString(String str) {
Objects.requireNonNull(str);
return toCString(str.getBytes());
}

/**
* Converts a Java string into a null-terminated C string, using the given {@link java.nio.charset.Charset charset},
* storing the result into a new native memory segment, associated with a fresh {@link ResourceScope#ofDefault() default scope}.
* <p>
* This method always replaces malformed-input and unmappable-character
* sequences with this charset's default replacement byte array. The
* {@link java.nio.charset.CharsetEncoder} class should be used when more
* control over the encoding process is required.
*
* @param str the Java string to be converted into a C string.
* @param charset The {@link java.nio.charset.Charset} to be used to compute the contents of the C string.
* @return a new native memory segment containing the converted C string.
*/
static MemorySegment toCString(String str, Charset charset) {
Objects.requireNonNull(str);
Objects.requireNonNull(charset);
return toCString(str.getBytes(charset));
}

/**
* Converts a Java string into a null-terminated C string, using the platform's default charset,
* storing the result into a native memory segment allocated using the provided allocator.
@@ -472,12 +419,6 @@ private static void copy(MemorySegment addr, byte[] bytes) {
MemoryAccess.setByteAtOffset(addr, bytes.length, (byte)0);
}

private static MemorySegment toCString(byte[] bytes) {
MemorySegment segment = MemorySegment.allocateNative(bytes.length + 1, 1L);
copy(segment, bytes);
return segment;
}

private static MemorySegment toCString(byte[] bytes, SegmentAllocator allocator) {
MemorySegment addr = allocator.allocate(bytes.length + 1, 1L);
copy(addr, bytes);
@@ -591,19 +532,6 @@ static void freeMemory(MemoryAddress addr) {
*/
MemoryAddress vargAsAddress(MemoryLayout layout);

/**
* Reads the next value as a {@code MemorySegment}, and advances this va list's position.
* <p>
* The memory segment returned by this method is associated with a fresh {@link ResourceScope#ofDefault() default scope}.
*
* @param layout the layout of the value
* @return the value read as an {@code MemorySegment}
* @throws IllegalStateException if the resource scope associated with this instance has been closed
* (see {@link #scope()}).
* @throws IllegalArgumentException if the given memory layout is not compatible with {@code MemorySegment}
*/
MemorySegment vargAsSegment(MemoryLayout layout);

/**
* Reads the next value as a {@code MemorySegment}, and advances this va list's position.
* <p>
@@ -657,7 +585,7 @@ static void freeMemory(MemoryAddress addr) {
* <p>
* This method only copies the va list cursor itself and not the memory that may be attached to the
* va list which holds its elements. That means that if this va list was created with the
* {@link #make(Consumer)} method, closing this va list will also release the native memory that holds its
* {@link #make(Consumer, ResourceScope)} method, closing this va list will also release the native memory that holds its
* elements, making the copy unusable.
*
* @return a copy of this C {@code va_list}.
@@ -713,26 +641,6 @@ static VaList ofAddress(MemoryAddress address, ResourceScope scope) {
return SharedUtils.newVaListOfAddress(address, scope);
}

/**
* Constructs a new {@code VaList} using a builder (see {@link Builder}), associated with a fresh
* a fresh {@link ResourceScope#ofDefault() default scope}.
* <p>
* If this method needs to allocate native memory, such memory will be managed by the same scope which also
* manages the returned valist instance; as such, this memory will be released only when the returned
* valist instance becomes <a href="../../../java/lang/ref/package.html#reachability">unreachable</a>.
* <p>
* Note that when there are no elements added to the created va list,
* this method will return the same as {@link #empty()}.
*
* @param actions a consumer for a builder (see {@link Builder}) which can be used to specify the elements
* of the underlying C {@code va_list}.
* @return a new {@code VaList} instance backed by a fresh C {@code va_list}.
*/
static VaList make(Consumer<Builder> actions) {
Objects.requireNonNull(actions);
return SharedUtils.newVaList(actions, MemoryScope.createDefault());
}

/**
* Constructs a new {@code VaList} using a builder (see {@link Builder}), associated with a given
* {@link ResourceScope resource scope}.
@@ -88,32 +88,6 @@ default MemoryAddress address() {
*/
long segmentOffset(MemorySegment segment);

/**
* Returns a shared native memory segment with given size, and whose base address is this address. This method
* can be useful when interacting with custom native memory sources (e.g. custom allocators), where an address to some
* underlying memory region is typically obtained from native code (often as a plain {@code long} value).
* The returned segment is associated with the {@link ResourceScope#globalScope() global} resource scope.
* <p>
* Clients should ensure that the address and bounds refers to a valid region of memory that is accessible for reading and,
* if appropriate, writing; an attempt to access an invalid memory location from Java code will either return an arbitrary value,
* have no visible effect, or cause an unspecified exception to be thrown.
* <p>
* This method is equivalent to the following code:
* <pre>{@code
asSegment(byteSize, null, ResourceScope.globalScope());
* }</pre>
* This method is <em>restricted</em>. Restricted methods are unsafe, and, if used incorrectly, their use might crash
* the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
* restricted methods, and use safe and supported functionalities, where possible.
*
* @param bytesSize the desired size.
* @return a new native memory segment with given base address and size.
* @throws IllegalArgumentException if {@code bytesSize <= 0}.
* @throws UnsupportedOperationException if this address is an heap address.
*/
@NativeAccess
MemorySegment asSegment(long bytesSize);

/**
* Returns a native memory segment with given size and resource scope, and whose base address is this address. This method
* can be useful when interacting with custom native memory sources (e.g. custom allocators), where an address to some
@@ -62,8 +62,8 @@
* <h2>Constructing memory segments</h2>
*
* There are multiple ways to obtain a memory segment. First, memory segments backed by off-heap memory can
* be allocated using one of the many factory methods provided (see {@link MemorySegment#allocateNative(MemoryLayout)},
* {@link MemorySegment#allocateNative(long)} and {@link MemorySegment#allocateNative(long, long)}). Memory segments obtained
* be allocated using one of the many factory methods provided (see {@link MemorySegment#allocateNative(MemoryLayout, ResourceScope)},
* {@link MemorySegment#allocateNative(long, ResourceScope)} and {@link MemorySegment#allocateNative(long, long, ResourceScope)}). Memory segments obtained
* in this way are called <em>native memory segments</em>.
* <p>
* It is also possible to obtain a memory segment backed by an existing heap-allocated Java array,
@@ -79,7 +79,7 @@
* by native memory.
* <p>
* Finally, it is also possible to obtain a memory segment backed by a memory-mapped file using the factory method
* {@link MemorySegment#mapFile(Path, long, long, FileChannel.MapMode)}. Such memory segments are called <em>mapped memory segments</em>;
* {@link MemorySegment#mapFile(Path, long, long, FileChannel.MapMode, ResourceScope)}. Such memory segments are called <em>mapped memory segments</em>;
* mapped memory segments are associated with an underlying file descriptor. For more operations on mapped memory segments, please refer to the
* {@link MappedMemorySegments} class.
*
@@ -286,7 +286,7 @@ default MemorySegment asSlice(MemoryAddress newBase) {

/**
* Is this a mapped segment? Returns true if this segment is a mapped memory segment,
* created using the {@link #mapFile(Path, long, long, FileChannel.MapMode)} factory, or a buffer segment
* created using the {@link #mapFile(Path, long, long, FileChannel.MapMode, ResourceScope)} factory, or a buffer segment
* derived from a {@link java.nio.MappedByteBuffer} using the {@link #ofByteBuffer(ByteBuffer)} factory.
* @return {@code true} if this segment is a mapped segment.
*/
@@ -553,26 +553,6 @@ static MemorySegment ofArray(double[] arr) {
return HeapMemorySegmentImpl.OfDouble.fromArray(arr);
}

/**
* Creates a new confined native memory segment that models a newly allocated block of off-heap memory with given layout.
* The returned segment is associated with a fresh {@link ResourceScope#ofDefault() default scope}. Resources associated with this
* segment will be automatically released when the returned segment (or any slices and views derived from it) is no longer in use.
* <p>
* This is equivalent to the following code:
* <blockquote><pre>{@code
allocateNative(layout.bytesSize(), layout.bytesAlignment());
* }</pre></blockquote>
* <p>
* The block of off-heap memory associated with the returned native memory segment is initialized to zero.
*
* @param layout the layout of the off-heap memory block backing the native memory segment.
* @return a new native memory segment.
* @throws IllegalArgumentException if the specified layout has illegal size or alignment constraint.
*/
static MemorySegment allocateNative(MemoryLayout layout) {
return allocateNative(layout, MemoryScope.createDefault());
}

/**
* Creates a new confined native memory segment that models a newly allocated block of off-heap memory with given layout
* and resource scope. A client is responsible make sure that the resource scope associated to the returned segment is closed
@@ -596,26 +576,6 @@ static MemorySegment allocateNative(MemoryLayout layout, ResourceScope scope) {
return allocateNative(layout.byteSize(), layout.byteAlignment(), scope);
}

/**
* Creates a new confined native memory segment that models a newly allocated block of off-heap memory with given size (in bytes).
* The returned segment is associated with a fresh {@link ResourceScope#ofDefault() default scope}. Resources associated with this
* segment will be automatically released when the returned segment (or any slices and views derived from it) is no longer in use.
* <p>
* This is equivalent to the following code:
* <blockquote><pre>{@code
allocateNative(bytesSize, 1);
* }</pre></blockquote>
* <p>
* The block of off-heap memory associated with the returned native memory segment is initialized to zero.
*
* @param bytesSize the size (in bytes) of the off-heap memory block backing the native memory segment.
* @return a new native memory segment.
* @throws IllegalArgumentException if {@code bytesSize <= 0}.
*/
static MemorySegment allocateNative(long bytesSize) {
return allocateNative(bytesSize, 1);
}

/**
* Creates a new confined native memory segment that models a newly allocated block of off-heap memory with given size (in bytes)
* and resource scope. A client is responsible make sure that the resource scope associated to the returned segment is closed
@@ -637,24 +597,6 @@ static MemorySegment allocateNative(long bytesSize, ResourceScope scope) {
return allocateNative(bytesSize, 1, scope);
}

/**
* Creates a new confined native memory segment that models a newly allocated block of off-heap memory with given size
* and alignment constraints (in bytes). The returned segment is associated with a fresh {@link ResourceScope#ofDefault() default scope}.
* Resources associated with this segment will be automatically released when the returned segment
* (or any slices and views derived from it) is no longer in use.
* <p>
* The block of off-heap memory associated with the returned native memory segment is initialized to zero.
*
* @param bytesSize the size (in bytes) of the off-heap memory block backing the native memory segment.
* @param alignmentBytes the alignment constraint (in bytes) of the off-heap memory block backing the native memory segment.
* @return a new native memory segment.
* @throws IllegalArgumentException if {@code bytesSize <= 0}, {@code alignmentBytes <= 0}, or if {@code alignmentBytes}
* is not a power of 2.
*/
static MemorySegment allocateNative(long bytesSize, long alignmentBytes) {
return allocateNative(bytesSize, alignmentBytes, MemoryScope.createDefault());
}

/**
* Creates a new confined native memory segment that models a newly allocated block of off-heap memory with given size
* (in bytes), alignment constraint (in bytes) and resource scope. A client is responsible make sure that the resource
@@ -684,39 +626,6 @@ static MemorySegment allocateNative(long bytesSize, long alignmentBytes, Resourc
return NativeMemorySegmentImpl.makeNativeSegment(bytesSize, alignmentBytes, (MemoryScope) scope);
}

/**
* Creates a new mapped memory segment that models a memory-mapped region of a file from a given path.
* The returned segment is associated with a fresh {@link ResourceScope#ofDefault() default scope}. Resources associated with this
* segment will be automatically released when the returned segment (or any slices and views derived from it) is no longer in use.
* <p>
* This is equivalent to the following code:
* <blockquote><pre>{@code
mapFile(path, bytesOffset, bytesSize, mapMode, ResourceScope.ofShared(Cleaner.create()));
* }</pre></blockquote>
*
* @implNote When obtaining a mapped segment from a newly created file, the initialization state of the contents of the block
* of mapped memory associated with the returned mapped memory segment is unspecified and should not be relied upon.
*
* @param path the path to the file to memory map.
* @param bytesOffset the offset (expressed in bytes) within the file at which the mapped segment is to start.
* @param bytesSize the size (in bytes) of the mapped memory backing the memory segment.
* @param mapMode a file mapping mode, see {@link FileChannel#map(FileChannel.MapMode, long, long)}; the chosen mapping mode
* might affect the behavior of the returned memory mapped segment (see {@link MappedMemorySegments#force(MemorySegment)}).
* @return a new mapped memory segment.
* @throws IllegalArgumentException if {@code bytesOffset < 0}.
* @throws IllegalArgumentException if {@code bytesSize < 0}.
* @throws UnsupportedOperationException if an unsupported map mode is specified, or if the {@code path} is associated
* with a provider that does not support creating file channels.
* @throws IOException if the specified path does not point to an existing file, or if some other I/O error occurs.
* @throws SecurityException If a security manager is installed and it denies an unspecified permission required by the implementation.
* In the case of the default provider, the {@link SecurityManager#checkRead(String)} method is invoked to check
* read access if the file is opened for reading. The {@link SecurityManager#checkWrite(String)} method is invoked to check
* write access if the file is opened for writing.
*/
static MemorySegment mapFile(Path path, long bytesOffset, long bytesSize, FileChannel.MapMode mapMode) throws IOException {
return mapFile(path, bytesOffset, bytesSize, mapMode, MemoryScope.createDefault());
}

/**
* Creates a new mapped memory segment that models a memory-mapped region of a file from a given path.
* <p>

0 comments on commit a4ba76c

Please sign in to comment.