8256865: Foreign Memory Access and Linker API are missing NPE checks

Reviewed-by: jvernee, sundar, chegar

Author: mcimadamore

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/AbstractLayout.java

@@ -62,6 +62,7 @@ public AbstractLayout(OptionalLong size, long alignment, Map<String, Constable>
 
     @Override
     public AbstractLayout withName(String name) {
+        Objects.requireNonNull(name);
         return withAttribute(LAYOUT_NAME, name);
     }
 
@@ -72,6 +73,7 @@ public final Optional<String> name() {
 
     @Override
     public Optional<Constable> attribute(String name) {
+        Objects.requireNonNull(name);
         return Optional.ofNullable(attributes.get(name));
     }
 
@@ -82,6 +84,7 @@ public Stream<String> attributes() {
 
     @Override
     public AbstractLayout withAttribute(String name, Constable value) {
+        Objects.requireNonNull(name);
         Map<String, Constable> newAttributes = new HashMap<>(attributes);
         newAttributes.put(name, value);
         return dup(alignment, newAttributes);

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/CLinker.java

@@ -36,6 +36,7 @@
 import java.nio.charset.Charset;
 import java.util.Objects;
 import java.util.function.Consumer;
+import java.util.stream.Stream;
 
 import static jdk.internal.foreign.PlatformLayouts.*;
 
@@ -94,6 +95,9 @@
  * {@link #asVarArg(MemoryLayout)} is used to create the memory layouts for each parameter corresponding to a variadic
  * argument in a specialized function descriptor.
  *
+ * <p> Unless otherwise specified, passing a {@code null} argument, or an array argument containing one or more {@code null}
+ * elements to a method in this class causes a {@link NullPointerException NullPointerException} to be thrown. </p>
+ *
  * @apiNote In the future, if the Java language permits, {@link CLinker}
  * may become a {@code sealed} interface, which would prohibit subclassing except by
  * explicitly permitted types.
@@ -186,14 +190,16 @@ static CLinker getInstance() {
     MemoryLayout C_VA_LIST = pick(SysV.C_VA_LIST, Win64.C_VA_LIST, AArch64.C_VA_LIST);
 
     /**
-     * Returns a memory layout that is suitable to use the layout for variadic arguments.
+     * Returns a memory layout that is suitable to use as the layout for variadic arguments in a specialized
+     * function descriptor.
      * @param <T> the memory layout type
-     * @param ml the layout the adapt
+     * @param layout the layout the adapt
      * @return a potentially newly created layout with the right attributes
      */
     @SuppressWarnings("unchecked")
-    static <T extends MemoryLayout> T asVarArg(T ml) {
-        return (T) PlatformLayouts.asVarArg(ml);
+    static <T extends MemoryLayout> T asVarArg(T layout) {
+        Objects.requireNonNull(layout);
+        return (T) PlatformLayouts.asVarArg(layout);
     }
 
     /**
@@ -207,7 +213,6 @@ static <T extends MemoryLayout> T asVarArg(T ml) {
      *
      * @param str the Java string to be converted into a C string.
      * @return a new native memory segment containing the converted C string.
-     * @throws NullPointerException if {@code str == null}.
      */
     static MemorySegment toCString(String str) {
         Objects.requireNonNull(str);
@@ -226,7 +231,6 @@ static MemorySegment toCString(String str) {
      * @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.
-     * @throws NullPointerException if either {@code str == null} or {@code charset == null}.
      */
     static MemorySegment toCString(String str, Charset charset) {
         Objects.requireNonNull(str);
@@ -246,7 +250,6 @@ static MemorySegment toCString(String str, Charset charset) {
      * @param str the Java string to be converted into a C string.
      * @param scope the scope to be used for the native segment allocation.
      * @return a new native memory segment containing the converted C string.
-     * @throws NullPointerException if either {@code str == null} or {@code scope == null}.
      */
     static MemorySegment toCString(String str, NativeScope scope) {
         Objects.requireNonNull(str);
@@ -267,7 +270,6 @@ static MemorySegment toCString(String str, NativeScope scope) {
      * @param charset The {@link java.nio.charset.Charset} to be used to compute the contents of the C string.
      * @param scope the scope to be used for the native segment allocation.
      * @return a new native memory segment containing the converted C string.
-     * @throws NullPointerException if either {@code str == null}, {@code charset == null} or {@code scope == null}.
      */
     static MemorySegment toCString(String str, Charset charset, NativeScope scope) {
         Objects.requireNonNull(str);
@@ -289,11 +291,11 @@ static MemorySegment toCString(String str, Charset charset, NativeScope scope) {
      * restricted methods, and use safe and supported functionalities, where possible.
      * @param addr the address at which the string is stored.
      * @return a Java string with the contents of the null-terminated C string at given address.
-     * @throws NullPointerException if {@code addr == null}
      * @throws IllegalArgumentException if the size of the native string is greater than the largest string supported by the platform.
      */
     static String toJavaStringRestricted(MemoryAddress addr) {
         Utils.checkRestrictedAccess("CLinker.toJavaStringRestricted");
+        Objects.requireNonNull(addr);
         return SharedUtils.toJavaStringInternal(NativeMemorySegmentImpl.EVERYTHING, addr.toRawLongValue(), Charset.defaultCharset());
     }
 
@@ -311,7 +313,6 @@ static String toJavaStringRestricted(MemoryAddress addr) {
      * @param addr the address at which the string is stored.
      * @param charset The {@link java.nio.charset.Charset} to be used to compute the contents of the Java string.
      * @return a Java string with the contents of the null-terminated C string at given address.
-     * @throws NullPointerException if {@code addr == null} or {@code charset == null}.
      * @throws IllegalArgumentException if the size of the native string is greater than the largest string supported by the platform.
      */
     static String toJavaStringRestricted(MemoryAddress addr, Charset charset) {
@@ -330,7 +331,6 @@ static String toJavaStringRestricted(MemoryAddress addr, Charset charset) {
      * over the decoding process is required.
      * @param addr the address at which the string is stored.
      * @return a Java string with the contents of the null-terminated C string at given address.
-     * @throws NullPointerException if {@code addr == null}
      * @throws IllegalArgumentException if the size of the native string is greater than the largest string supported by the platform.
      * @throws IllegalStateException if the size of the native string is greater than the size of the segment
      * associated with {@code addr}, or if {@code addr} is associated with a segment that is <em>not alive</em>.
@@ -350,7 +350,6 @@ static String toJavaString(MemorySegment addr) {
      * @param addr the address at which the string is stored.
      * @param charset The {@link java.nio.charset.Charset} to be used to compute the contents of the Java string.
      * @return a Java string with the contents of the null-terminated C string at given address.
-     * @throws NullPointerException if {@code addr == null} or {@code charset == null}.
      * @throws IllegalArgumentException if the size of the native string is greater than the largest string supported by the platform.
      * @throws IllegalStateException if the size of the native string is greater than the size of the segment
      * associated with {@code addr}, or if {@code addr} is associated with a segment that is <em>not alive</em>.
@@ -408,7 +407,6 @@ static MemoryAddress allocateMemoryRestricted(long size) {
      * restricted methods, and use safe and supported functionalities, where possible.
      *
      * @param addr memory address of the native memory to be freed
-     * @throws NullPointerException if {@code addr == null}.
      */
     static void freeMemoryRestricted(MemoryAddress addr) {
         Utils.checkRestrictedAccess("CLinker.freeMemoryRestricted");
@@ -429,6 +427,9 @@ static void freeMemoryRestricted(MemoryAddress addr) {
      * As such, this interface only supports reading {@code int}, {@code double},
      * and any other type that fits into a {@code long}.
      *
+     * <p> Unless otherwise specified, passing a {@code null} argument, or an array argument containing one or more {@code null}
+     * elements to a method in this class causes a {@link NullPointerException NullPointerException} to be thrown. </p>
+     *
      * @apiNote In the future, if the Java language permits, {@link VaList}
      * may become a {@code sealed} interface, which would prohibit subclassing except by
      * explicitly permitted types.
@@ -597,6 +598,7 @@ interface VaList extends Addressable, AutoCloseable {
          */
         static VaList ofAddressRestricted(MemoryAddress address) {
             Utils.checkRestrictedAccess("VaList.ofAddressRestricted");
+            Objects.requireNonNull(address);
             return SharedUtils.newVaListOfAddress(address);
         }
 
@@ -618,6 +620,7 @@ static VaList ofAddressRestricted(MemoryAddress address) {
          * @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, MemorySegment::allocateNative);
         }
 
@@ -639,6 +642,8 @@ static VaList make(Consumer<Builder> actions) {
          * @return a new {@code VaList} instance backed by a fresh C {@code va_list}.
          */
         static VaList make(Consumer<Builder> actions, NativeScope scope) {
+            Objects.requireNonNull(actions);
+            Objects.requireNonNull(scope);
             return SharedUtils.newVaList(actions, SharedUtils.Allocator.ofScope(scope));
         }
 
@@ -656,6 +661,9 @@ static VaList empty() {
         /**
          * A builder interface used to construct a C {@code va_list}.
          *
+         * <p> Unless otherwise specified, passing a {@code null} argument, or an array argument containing one or more {@code null}
+         * elements to a method in this class causes a {@link NullPointerException NullPointerException} to be thrown. </p>
+         *
          * @apiNote In the future, if the Java language permits, {@link Builder}
          * may become a {@code sealed} interface, which would prohibit subclassing except by
          * explicitly permitted types.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/FunctionDescriptor.java

@@ -42,6 +42,9 @@
 /**
  * A function descriptor is made up of zero or more argument layouts and zero or one return layout. A function descriptor
  * is used to model the signature of foreign functions.
+ *
+ * <p> Unless otherwise specified, passing a {@code null} argument, or an array argument containing one or more {@code null}
+ * elements to a method in this class causes a {@link NullPointerException NullPointerException} to be thrown. </p>
  */
 public final class FunctionDescriptor implements Constable {
 
@@ -68,6 +71,7 @@ private FunctionDescriptor(MemoryLayout resLayout, Map<String, Constable> attrib
      * @return the attribute with the given name (if it exists).
      */
     public Optional<Constable> attribute(String name) {
+        Objects.requireNonNull(name);
         return Optional.ofNullable(attributes.get(name));
     }
 
@@ -90,6 +94,7 @@ public Stream<String> attributes() {
      * @return a new function descriptor which features the same attributes as this descriptor, plus the newly specified attribute.
      */
     public FunctionDescriptor withAttribute(String name, Constable value) {
+        Objects.requireNonNull(name);
         Map<String, Constable> newAttributes = new HashMap<>(attributes);
         newAttributes.put(name, value);
         return new FunctionDescriptor(resLayout, newAttributes, argLayouts);
@@ -116,10 +121,10 @@ public List<MemoryLayout> argumentLayouts() {
      * @param resLayout the return layout.
      * @param argLayouts the argument layouts.
      * @return the new function descriptor.
-     * @throws NullPointerException if any of the argument layouts, or the return layout is null.
      */
     public static FunctionDescriptor of(MemoryLayout resLayout, MemoryLayout... argLayouts) {
         Objects.requireNonNull(resLayout);
+        Objects.requireNonNull(argLayouts);
         Arrays.stream(argLayouts).forEach(Objects::requireNonNull);
         return new FunctionDescriptor(resLayout, Map.of(), argLayouts);
     }
@@ -128,9 +133,9 @@ public static FunctionDescriptor of(MemoryLayout resLayout, MemoryLayout... argL
      * Create a function descriptor with given argument layouts and no return layout.
      * @param argLayouts the argument layouts.
      * @return the new function descriptor.
-     * @throws NullPointerException if any of the argument layouts is null.
      */
     public static FunctionDescriptor ofVoid(MemoryLayout... argLayouts) {
+        Objects.requireNonNull(argLayouts);
         Arrays.stream(argLayouts).forEach(Objects::requireNonNull);
         return new FunctionDescriptor(null, Map.of(), argLayouts);
     }
@@ -140,9 +145,9 @@ public static FunctionDescriptor ofVoid(MemoryLayout... argLayouts) {
      * of this function descriptor.
      * @param addedLayouts the argument layouts to append.
      * @return the new function descriptor.
-     * @throws NullPointerException if any of the new argument layouts is null.
      */
     public FunctionDescriptor withAppendedArgumentLayouts(MemoryLayout... addedLayouts) {
+        Objects.requireNonNull(addedLayouts);
         Arrays.stream(addedLayouts).forEach(Objects::requireNonNull);
         MemoryLayout[] newLayouts = Arrays.copyOf(argLayouts, argLayouts.length + addedLayouts.length);
         System.arraycopy(addedLayouts, 0, newLayouts, argLayouts.length, addedLayouts.length);
@@ -153,7 +158,6 @@ public FunctionDescriptor withAppendedArgumentLayouts(MemoryLayout... addedLayou
      * Create a new function descriptor with the given memory layout as the new return layout.
      * @param newReturn the new return layout.
      * @return the new function descriptor.
-     * @throws NullPointerException if the new return layout is null.
      */
     public FunctionDescriptor withReturnLayout(MemoryLayout newReturn) {
         Objects.requireNonNull(newReturn);

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/GroupLayout.java

@@ -52,6 +52,9 @@
  * {@code GroupLayout} may have unpredictable results and should be avoided.
  * The {@code equals} method should be used for comparisons.
  *
+ * <p> Unless otherwise specified, passing a {@code null} argument, or an array argument containing one or more {@code null}
+ * elements to a method in this class causes a {@link NullPointerException NullPointerException} to be thrown. </p>
+ *
  * @implSpec
  * This class is immutable and thread-safe.
  */

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/LibraryLookup.java

@@ -56,6 +56,9 @@
  * <p>
  * To allow for a library to be unloaded, a client will have to discard any strong references it
  * maintains, directly, or indirectly to a lookup object associated with given library.
+ *
+ * <p> Unless otherwise specified, passing a {@code null} argument, or an array argument containing one or more {@code null}
+ * elements to a method in this class causes a {@link NullPointerException NullPointerException} to be thrown. </p>
  */
 public interface LibraryLookup {
 

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MappedMemorySegments.java

@@ -28,6 +28,7 @@
 import jdk.internal.foreign.MappedMemorySegmentImpl;
 
 import java.nio.MappedByteBuffer;
+import java.util.Objects;
 
 /**
  * This class provides capabilities to manipulate mapped memory segments, such as {@link #force(MemorySegment)},
@@ -42,6 +43,9 @@
  * with the desired parameters; the returned address can be easily wrapped into a memory segment, using
  * {@link MemoryAddress#ofLong(long)} and {@link MemoryAddress#asSegmentRestricted(long, Runnable, Object)}.
  *
+ * <p> Unless otherwise specified, passing a {@code null} argument, or an array argument containing one or more {@code null}
+ * elements to a method in this class causes a {@link NullPointerException NullPointerException} to be thrown. </p>
+ *
  * @implNote
  * The behavior of some the methods in this class (see {@link #load(MemorySegment)}, {@link #unload(MemorySegment)} and
  * {@link #isLoaded(MemorySegment)}) is highly platform-dependent; as a result, calling these methods might
@@ -151,6 +155,7 @@ public static void force(MemorySegment segment) {
     }
 
     static MappedMemorySegmentImpl toMappedSegment(MemorySegment segment) {
+        Objects.requireNonNull(segment);
         if (segment instanceof MappedMemorySegmentImpl) {
             return (MappedMemorySegmentImpl)segment;
         } else {