Rename SystemABI to ForeignLinker, and move C support to a separate class.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/SystemABI.java → src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/CSupport.java

@@ -1,5 +1,5 @@
 /*
- *  Copyright (c) 2019, 2020, Oracle and/or its affiliates. All rights reserved.
+ *  Copyright (c) 2020, Oracle and/or its affiliates. All rights reserved.
  *  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  *  This code is free software; you can redistribute it and/or modify it
@@ -27,132 +27,79 @@
 
 import jdk.internal.foreign.Utils;
 import jdk.internal.foreign.abi.SharedUtils;
-import jdk.internal.foreign.abi.UpcallStubs;
-import jdk.internal.foreign.abi.aarch64.AArch64ABI;
-import jdk.internal.foreign.abi.x64.sysv.SysVx64ABI;
-import jdk.internal.foreign.abi.x64.windows.Windowsx64ABI;
 
-import java.lang.invoke.MethodHandle;
-import java.lang.invoke.MethodType;
 import java.nio.ByteOrder;
-import java.util.Optional;
 
 /**
- * This class models a system application binary interface (ABI).
- *
- * Instances of this class can be obtained by calling {@link SystemABI#getSystemABI()}
+ * A set of utilities for working with libraries using the C language/ABI
  */
-public interface SystemABI {
-    /**
-     * The name of the SysV ABI
-     */
-    String ABI_SYSV = "SysV";
-
-    /**
-     * The name of the Windows ABI
-     */
-    String ABI_WINDOWS = "Windows";
-
-    /**
-     * The name of the AArch64 ABI
-     */
-    String ABI_AARCH64 = "AArch64";
-
+public class CSupport {
     /**
-     * memory layout attribute key for abi native type
-     */
-    String NATIVE_TYPE = "abi/native-type";
-
-    /**
-     * Obtain a method handle which can be used to call a given native function.
-     *
-     * @param symbol downcall symbol.
-     * @param type the method type.
-     * @param function the function descriptor.
-     * @return the downcall method handle.
-     */
-    MethodHandle downcallHandle(MemoryAddress symbol, MethodType type, FunctionDescriptor function);
-
-    /**
-     * Allocates a native stub segment which contains executable code to upcall into a given method handle.
-     * As such, the base address of the returned stub segment can be passed to other foreign functions
-     * (as a function pointer). The returned segment is <em>not</em> thread-confined, and it only features
-     * the {@link MemorySegment#CLOSE} access mode. When the returned segment is closed,
-     * the corresponding native stub will be deallocated.
-     *
-     * @param target the target method handle.
-     * @param function the function descriptor.
-     * @return the native stub segment.
-     */
-    MemorySegment upcallStub(MethodHandle target, FunctionDescriptor function);
-
-    /**
-     * Returns the name of this ABI.
-     *
-     * @return the name
+     * Obtain a linker that uses the de facto C ABI of the current system to do it's linking.
+     * <p>
+     * This method is <em>restricted</em>. Restricted method are unsafe, and, if used incorrectly, their use might crash
+     * the JVM crash or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
+     * restricted methods, and use safe and supported functionalities, where possible.
+     * @return a linker for this system.
+     * @throws IllegalAccessError if the runtime property {@code foreign.restricted} is not set to either
+     * {@code permit}, {@code warn} or {@code debug} (the default value is set to {@code deny}).
      */
-    String name();
+    public static ForeignLinker getSystemLinker() {
+        Utils.checkRestrictedAccess("CSupport.getSystemLinker");
+        return SharedUtils.getSystemLinker();
+    }
 
     /**
      * The {@code _Bool} native type.
      */
-    ValueLayout C_BOOL = Utils.pick(SysV.C_BOOL, Win64.C_BOOL, AArch64.C_BOOL);
-
+    public static final ValueLayout C_BOOL = Utils.pick(SysV.C_BOOL, Win64.C_BOOL, AArch64.C_BOOL);
     /**
      * The {@code char} native type.
      */
-    ValueLayout C_CHAR = Utils.pick(SysV.C_CHAR, Win64.C_CHAR, AArch64.C_CHAR);
-
+    public static final ValueLayout C_CHAR = Utils.pick(SysV.C_CHAR, Win64.C_CHAR, AArch64.C_CHAR);
     /**
      * The {@code short} native type.
      */
-    ValueLayout C_SHORT = Utils.pick(SysV.C_SHORT, Win64.C_SHORT, AArch64.C_SHORT);
-
+    public static final ValueLayout C_SHORT = Utils.pick(SysV.C_SHORT, Win64.C_SHORT, AArch64.C_SHORT);
     /**
      * The {@code int} native type.
      */
-    ValueLayout C_INT = Utils.pick(SysV.C_INT, Win64.C_INT, AArch64.C_INT);
-
+    public static final ValueLayout C_INT = Utils.pick(SysV.C_INT, Win64.C_INT, AArch64.C_INT);
     /**
      * The {@code long} native type.
      */
-    ValueLayout C_LONG = Utils.pick(SysV.C_LONG, Win64.C_LONG, AArch64.C_LONG);
-
+    public static final ValueLayout C_LONG = Utils.pick(SysV.C_LONG, Win64.C_LONG, AArch64.C_LONG);
     /**
      * The {@code long long} native type.
      */
-    ValueLayout C_LONGLONG = Utils.pick(SysV.C_LONGLONG, Win64.C_LONGLONG, AArch64.C_LONGLONG);
-
+    public static final ValueLayout C_LONGLONG = Utils.pick(SysV.C_LONGLONG, Win64.C_LONGLONG, AArch64.C_LONGLONG);
     /**
      * The {@code float} native type.
      */
-    ValueLayout C_FLOAT = Utils.pick(SysV.C_FLOAT, Win64.C_FLOAT, AArch64.C_FLOAT);
-
+    public static final ValueLayout C_FLOAT = Utils.pick(SysV.C_FLOAT, Win64.C_FLOAT, AArch64.C_FLOAT);
     /**
      * The {@code double} native type.
      */
-    ValueLayout C_DOUBLE = Utils.pick(SysV.C_DOUBLE, Win64.C_DOUBLE, AArch64.C_DOUBLE);
-
+    public static final ValueLayout C_DOUBLE = Utils.pick(SysV.C_DOUBLE, Win64.C_DOUBLE, AArch64.C_DOUBLE);
     /**
      * The {@code long double} native type.
      */
-    ValueLayout C_LONGDOUBLE = Utils.pick(SysV.C_LONGDOUBLE, Win64.C_LONGDOUBLE, AArch64.C_LONGDOUBLE);
-
+    public static final ValueLayout C_LONGDOUBLE = Utils.pick(SysV.C_LONGDOUBLE, Win64.C_LONGDOUBLE, AArch64.C_LONGDOUBLE);
     /**
      * The {@code T*} native type.
      */
-    ValueLayout C_POINTER = Utils.pick(SysV.C_POINTER, Win64.C_POINTER, AArch64.C_POINTER);
+    public static final ValueLayout C_POINTER = Utils.pick(SysV.C_POINTER, Win64.C_POINTER, AArch64.C_POINTER);
 
     /**
      * This class defines layout constants modelling standard primitive types supported by the x64 SystemV ABI.
      */
-    final class SysV {
+    public static final class SysV {
         private SysV() {
             //just the one
         }
 
         /**
-         * The name of the SysV ABI
+         * The name of the SysV linker ({@see ForeignLinker#name})
          */
         public static final String NAME = "SysV";
 
@@ -236,14 +183,14 @@ public enum ArgumentClass {
     /**
      * This class defines layout constants modelling standard primitive types supported by the x64 Windows ABI.
      */
-    final class Win64 {
+    public static final class Win64 {
 
         private Win64() {
             //just the one
         }
 
         /**
-         * The name of the Windows ABI
+         * The name of the Windows linker ({@see ForeignLinker#name})
          */
         public final static String NAME = "Windows";
 
@@ -325,14 +272,14 @@ public static ValueLayout asVarArg(ValueLayout l) {
     /**
      * This class defines layout constants modelling standard primitive types supported by the AArch64 ABI.
      */
-    final class AArch64 {
+    public static final class AArch64 {
 
         private AArch64() {
             //just the one
         }
 
         /**
-         * The name of the AArch64 ABI
+         * The name of the AArch64 linker ({@see ForeignLinker#name})
          */
         public final static String NAME = "AArch64";
 
@@ -404,19 +351,4 @@ public enum ArgumentClass {
         public static final ValueLayout C_POINTER = MemoryLayouts.BITS_64_LE
                 .withAttribute(CLASS_ATTRIBUTE_NAME, ArgumentClass.POINTER);
     }
-
-    /**
-     * Obtain an instance of the system ABI.
-     * <p>
-     * This method is <em>restricted</em>. Restricted method are unsafe, and, if used incorrectly, their use might crash
-     * the JVM crash or, worse, silently result in memory corruption. Thus, clients should refrain from depending on
-     * restricted methods, and use safe and supported functionalities, where possible.
-     * @return system ABI.
-     * @throws IllegalAccessError if the runtime property {@code foreign.restricted} is not set to either
-     * {@code permit}, {@code warn} or {@code debug} (the default value is set to {@code deny}).
-     */
-    static SystemABI getSystemABI() {
-        Utils.checkRestrictedAccess("SystemABI.getSystemABI");
-        return SharedUtils.getSystemABI();
-    }
 }

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

@@ -0,0 +1,67 @@
+/*
+ *  Copyright (c) 2019, 2020, Oracle and/or its affiliates. All rights reserved.
+ *  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ *  This code is free software; you can redistribute it and/or modify it
+ *  under the terms of the GNU General Public License version 2 only, as
+ *  published by the Free Software Foundation.  Oracle designates this
+ *  particular file as subject to the "Classpath" exception as provided
+ *  by Oracle in the LICENSE file that accompanied this code.
+ *
+ *  This code is distributed in the hope that it will be useful, but WITHOUT
+ *  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ *  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ *  version 2 for more details (a copy is included in the LICENSE file that
+ *  accompanied this code).
+ *
+ *  You should have received a copy of the GNU General Public License version
+ *  2 along with this work; if not, write to the Free Software Foundation,
+ *  Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ *   Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ *  or visit www.oracle.com if you need additional information or have any
+ *  questions.
+ *
+ */
+package jdk.incubator.foreign;
+
+import java.lang.invoke.MethodHandle;
+import java.lang.invoke.MethodType;
+
+/**
+ * This class can be used to link native functions as a {@link MethodHandle}, or to link Java
+ * methods as a native function pointer (modelled as a {@link MemorySegment}).
+ *
+ * Instances of this interface can be obtained for instance by calling {@link CSupport#getSystemLinker()}
+ */
+public interface ForeignLinker {
+    /**
+     * Obtain a method handle which can be used to call a given native function.
+     *
+     * @param symbol downcall symbol.
+     * @param type the method type.
+     * @param function the function descriptor.
+     * @return the downcall method handle.
+     */
+    MethodHandle downcallHandle(MemoryAddress symbol, MethodType type, FunctionDescriptor function);
+
+    /**
+     * Allocates a native stub segment which contains executable code to upcall into a given method handle.
+     * As such, the base address of the returned stub segment can be passed to other foreign functions
+     * (as a function pointer). The returned segment is <em>not</em> thread-confined, and it only features
+     * the {@link MemorySegment#CLOSE} access mode. When the returned segment is closed,
+     * the corresponding native stub will be deallocated.
+     *
+     * @param target the target method handle.
+     * @param function the function descriptor.
+     * @return the native stub segment.
+     */
+    MemorySegment upcallStub(MethodHandle target, FunctionDescriptor function);
+
+    /**
+     * Returns the name of this linker.
+     *
+     * @return the name
+     */
+    String name();
+}

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

@@ -38,7 +38,7 @@
  * <p>
  * Memory address instances generated by a library lookup will contain a strong reference to the originating lookup object,
  * therefore preventing library unloading; in turn method handle instances obtained from
- * {@link SystemABI#downcallHandle(MemoryAddress, MethodType, FunctionDescriptor)}) also maintain a strong reference
+ * {@link ForeignLinker#downcallHandle(MemoryAddress, MethodType, FunctionDescriptor)}) also maintain a strong reference
  * to the memory address parameter used for their construction. This means that there is always a strong reachability chain
  * from a native method handle to a lookup object (the one that was used to lookup the native library symbol the method handle
  * refers to); this is useful to prevent situations where a native library is unloaded in the middle of a native call.

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

@@ -26,15 +26,8 @@
 
 package jdk.incubator.foreign;
 
-import jdk.internal.foreign.abi.SharedUtils;
-import jdk.internal.foreign.abi.x64.windows.Windowsx64ABI;
-
 import java.nio.ByteOrder;
 
-import static jdk.incubator.foreign.SystemABI.ABI_AARCH64;
-import static jdk.incubator.foreign.SystemABI.ABI_SYSV;
-import static jdk.incubator.foreign.SystemABI.ABI_WINDOWS;
-
 /**
  * This class defines useful layout constants. Some of the constants defined in this class are explicit in both
  * size and byte order (see {@link #BITS_64_BE}), and can therefore be used to explicitly and unambiguously specify the

src/jdk.incubator.foreign/share/classes/jdk/internal/foreign/Utils.java

@@ -26,11 +26,11 @@
 
 package jdk.internal.foreign;
 
-import jdk.incubator.foreign.GroupLayout;
+import jdk.incubator.foreign.CSupport;
 import jdk.incubator.foreign.MemoryAddress;
 import jdk.incubator.foreign.MemoryHandles;
 import jdk.incubator.foreign.MemoryLayout;
-import jdk.incubator.foreign.SystemABI;
+import jdk.incubator.foreign.ForeignLinker;
 import jdk.incubator.foreign.ValueLayout;
 import jdk.internal.access.foreign.MemoryAddressProxy;
 import jdk.internal.foreign.abi.SharedUtils;
@@ -107,11 +107,11 @@ private static void throwIllegalAccessError(String value, String method) {
     }
 
     public static <Z extends MemoryLayout> Z pick(Z sysv, Z win64, Z aarch64) {
-        SystemABI abi = SharedUtils.getSystemABI();
+        ForeignLinker abi = SharedUtils.getSystemLinker();
         return switch (abi.name()) {
-            case SystemABI.SysV.NAME -> sysv;
-            case SystemABI.Win64.NAME -> win64;
-            case SystemABI.AArch64.NAME -> aarch64;
+            case CSupport.SysV.NAME -> sysv;
+            case CSupport.Win64.NAME -> win64;
+            case CSupport.AArch64.NAME -> aarch64;
             default -> throw new ExceptionInInitializerError("Unexpected ABI: " + abi.name());
         };
     }

src/jdk.incubator.foreign/share/classes/jdk/internal/foreign/abi/SharedUtils.java

@@ -24,19 +24,19 @@
  */
 package jdk.internal.foreign.abi;
 
+import jdk.incubator.foreign.ForeignLinker;
 import jdk.incubator.foreign.FunctionDescriptor;
 import jdk.incubator.foreign.GroupLayout;
 import jdk.incubator.foreign.MemoryAddress;
 import jdk.incubator.foreign.MemoryLayout;
 import jdk.incubator.foreign.MemorySegment;
 import jdk.incubator.foreign.SequenceLayout;
-import jdk.incubator.foreign.SystemABI;
 import jdk.incubator.foreign.ValueLayout;
 import jdk.internal.foreign.MemoryAddressImpl;
 import jdk.internal.foreign.Utils;
-import jdk.internal.foreign.abi.aarch64.AArch64ABI;
-import jdk.internal.foreign.abi.x64.sysv.SysVx64ABI;
-import jdk.internal.foreign.abi.x64.windows.Windowsx64ABI;
+import jdk.internal.foreign.abi.aarch64.AArch64Linker;
+import jdk.internal.foreign.abi.x64.sysv.SysVx64Linker;
+import jdk.internal.foreign.abi.x64.windows.Windowsx64Linker;
 
 import java.lang.invoke.MethodHandle;
 import java.lang.invoke.MethodHandles;
@@ -228,17 +228,17 @@ public static Class<?> primitiveCarrierForSize(long size) {
         throw new IllegalArgumentException("Size too large: " + size);
     }
 
-    public static SystemABI getSystemABI() {
+    public static ForeignLinker getSystemLinker() {
         String arch = System.getProperty("os.arch");
         String os = System.getProperty("os.name");
         if (arch.equals("amd64") || arch.equals("x86_64")) {
             if (os.startsWith("Windows")) {
-                return Windowsx64ABI.getInstance();
+                return Windowsx64Linker.getInstance();
             } else {
-                return SysVx64ABI.getInstance();
+                return SysVx64Linker.getInstance();
             }
         } else if (arch.equals("aarch64")) {
-            return AArch64ABI.getInstance();
+            return AArch64Linker.getInstance();
         }
         throw new UnsupportedOperationException("Unsupported os or arch: " + os + ", " + arch);
     }