Add Initial Java Support for GDS to KvikIO

java/README.md

@@ -0,0 +1,48 @@
+Java Bindings
+
+Summary
+These Java KvikIO bindings for GDS currently support only synchronous read and write IO operations using the underlying CuFile API. Support for batch IO and asynchronous operations are not yet supported.
+
+Dependencies
+The Java KvikIO bindings have been developed to work on Linux based systems and require CUDA to be installed and for GDS to be properly enabled. Instructions for how to install and enable GDS can be found on NVIDIA's website. To compile the shared library it is also necessary to have a JDK installed. To run the included example, it is also necessary to install JCuda as it is used to handle memory allocations and the transfer of data between host and GPU memory. JCuda jar files supporting CUDA 12.x can be found here:
+https://repo1.maven.org/maven2/org/jcuda/jcuda/12.0.0/jcuda-12.0.0.jar
+https://repo1.maven.org/maven2/org/jcuda/jcuda-natives/12.0.0/jcuda-natives-12.0.0.jar
+
+Compilation
+To recompile the .so file for your local system run the following command. Note: Update the command to reflect the directory where you have installed CUDA and your JDK.
+
+/usr/local/cuda/bin/nvcc -shared -o libCuFileJNI.so -I/usr/local/cuda/include/ -I/usr/lib/jvm/java-21-openjdk-amd64/include/ -I/usr/lib/jvm/java-21-openjdk-amd64/include/linux src/main/native/src/CuFileJni.cpp --compiler-options "-fPIC" -lcufile
+
+The resulting .so file must be in your JVM library path. If it is not already placed on your path in can be included when compiling and running your Java code by including an argument like the following:
+-Djava.library.path={path/to/your/so/file/}
+
+Examples
+An example for how to use the Java KvikIO bindings can be found in src/main/java/bindings/kvikio/example . Note: This example has a dependency on JCuda so ensure that when running the example the JCuda shared library files are on the JVM library path along with the libCuFileJNI.so file.
+
+Specific instructions to run the example from a terminal:
+Compile class files
+cd kvikio/java/src/main/java/bindings/kvikio/cufile
+javac \*.java
+
+Retrieve Jcuda jar files
+cd kvikio/java/
+mkdir lib
+cd lib
+wget https://repo1.maven.org/maven2/org/jcuda/jcuda/12.0.0/jcuda-12.0.0.jar
+wget https://repo1.maven.org/maven2/org/jcuda/jcuda-natives/12.0.0/jcuda-natives-12.0.0.jar
+
+Compile shared library
+cd kvikio/java/lib
+/usr/local/cuda/bin/nvcc -shared -o libCuFileJNI.so -I/usr/local/cuda/include/ -I/usr/lib/jvm/java-21-openjdk-amd64/include/ -I/usr/lib/jvm/java-21-openjdk-amd64/include/linux ../src/main/native/src/CuFileJni.cpp --compiler-options "-fPIC" -lcufile
+
+Setup a test file target NOTE: your mount directory may differ from /mnt/nvme, so update this command appropriately as well as example/Main.java to point to the correct file path.
+touch /mnt/nvme/java\_test
+
+Compile example file
+cd kvikio/java/src/main/java 
+javac -cp .:../../../lib/jcuda-12.0.0.jar:../../../lib/jcuda-natives-12.0.0.jar bindings/kvikio/example/Main.java
+
+Run example
+cd kvikio/java/src/main/java 
+java -cp .:../../../lib/jcuda-12.0.0.jar:../../../lib/jcuda-natives-12.0.0.jar -Djava.library.path=../../../lib/ bindings.kvikio.example.main
+

java/src/main/java/bindings/kvikio/cufile/CuFile.java

@@ -0,0 +1,29 @@
+package bindings.kvikio.cufile;
+
+public class CuFile {
+    private static boolean initialized = false;
+    private static CuFileDriver driver;
+
+    static {
+        initialize();
+    }
+
+    static synchronized void initialize() {
+        if (!initialized) {
+            try {
+                System.loadLibrary("CuFileJNI");
+                driver = new CuFileDriver();
+                Runtime.getRuntime().addShutdownHook(new Thread(() -> {
+                    driver.close();
+                  }));
+                initialized = true;
+            } catch (Throwable t) {
+                System.out.println("could not load cufile jni library");
+            }
+        }
+    }
+
+    public static boolean libraryLoaded() {
+        return initialized;
+    }
+}

java/src/main/java/bindings/kvikio/cufile/CuFileDriver.java

@@ -0,0 +1,19 @@
+package bindings.kvikio.cufile;
+
+
+final class CuFileDriver implements AutoCloseable {
+    private final long pointer;
+
+    CuFileDriver() {
+        pointer = create();
+    }
+
+    public void close() {
+        destroy(pointer);
+    }
+
+
+    private static native long create();
+
+    private static native void destroy(long pointer);
+}

java/src/main/java/bindings/kvikio/cufile/CuFileHandle.java

@@ -0,0 +1,23 @@
+package bindings.kvikio.cufile;
+
+abstract class CuFileHandle implements AutoCloseable {
+    private final long pointer;
+
+    static {
+      CuFile.initialize();
+    }
+
+    protected CuFileHandle(long pointer) {
+      this.pointer = pointer;
+    }
+
+    public void close() {
+      destroy(pointer);
+    }
+
+    protected long getPointer() {
+      return this.pointer;
+    }
+
+    private static native void destroy(long pointer);
+  }

java/src/main/java/bindings/kvikio/cufile/CuFileReadHandle.java

@@ -0,0 +1,17 @@
+package bindings.kvikio.cufile;
+
+public final class CuFileReadHandle extends CuFileHandle{
+
+    public CuFileReadHandle(String path) {
+        super(create(path));
+    }
+
+    public void read(long device_pointer, long size, long file_offset, long device_offset) {
+        readFile(getPointer(),device_pointer,size,file_offset,device_offset);
+    }
+
+    private static native long create(String path);
+
+    private static native void readFile(long file_pointer, long device_pointer, long size, long file_offset, long device_offset);
+
+}

java/src/main/java/bindings/kvikio/cufile/CuFileWriteHandle.java

@@ -0,0 +1,16 @@
+package bindings.kvikio.cufile;
+
+public final class CuFileWriteHandle extends CuFileHandle {
+
+    public CuFileWriteHandle(String path) {
+        super(create(path));
+    }
+
+    public void write(long device_pointer, long size, long file_offset, long buffer_offset) {
+        writeFile(getPointer(),device_pointer,size,file_offset,buffer_offset);
+    }
+
+    private static native long create(String path);
+
+    private static native void writeFile(long file_pointer, long device_pointer, long size, long file_offset, long buffer_offset);
+}

java/src/main/java/bindings/kvikio/example/Main.java

@@ -0,0 +1,73 @@
+package bindings.kvikio.example;
+
+import bindings.kvikio.cufile.CuFileReadHandle;
+import bindings.kvikio.cufile.CuFileWriteHandle;
+
+import static jcuda.runtime.cudaMemcpyKind.cudaMemcpyDeviceToHost;
+import static jcuda.runtime.cudaMemcpyKind.cudaMemcpyHostToDevice;
+
+import java.util.Arrays;
+
+import jcuda.NativePointerObject;
+import jcuda.Pointer;
+import jcuda.Sizeof;
+import jcuda.runtime.JCuda;
+
+class main {
+    public static void main(String []args)
+    {
+        // Allocate CUDA device memory
+        int numInts = 4;
+        Pointer pointer = new Pointer();
+        JCuda.cudaMalloc(pointer, numInts*Sizeof.INT);
+
+        // Build host arrays, print them out
+        int hostData[] = new int[numInts];
+        int hostDataFilled[] = new int[numInts];
+        for (int i = 0; i < numInts; ++i) {
+            hostDataFilled[i]=i;
+        }
+        System.out.println(Arrays.toString(hostData));
+        System.out.println(Arrays.toString(hostDataFilled));
+
+        // Obtain pointer value for allocated CUDA device memory
+        long pointerAddress = getPointerAddress(pointer);
+
+        // Copy filled data array to GPU and write to file
+        JCuda.cudaMemcpy(pointer,Pointer.to(hostDataFilled),numInts*Sizeof.INT,cudaMemcpyHostToDevice);
+        CuFileWriteHandle fw = new CuFileWriteHandle("/mnt/nvme/java_test");
+        fw.write(pointerAddress, numInts*Sizeof.INT,0,0);
+        fw.close();
+
+        // Clear data stored in GPU
+        JCuda.cudaMemcpy(pointer,Pointer.to(hostData),numInts*Sizeof.INT,cudaMemcpyHostToDevice);
+
+        // Read data back into GPU
+        CuFileReadHandle f = new CuFileReadHandle("/mnt/nvme/java_test");
+        f.read(pointerAddress,numInts*Sizeof.INT,0,0);
+        f.close();
+
+        // Copy data back to host and confirm what was written was read
+        JCuda.cudaMemcpy(Pointer.to(hostData), pointer, numInts*Sizeof.INT, cudaMemcpyDeviceToHost);
+        System.out.println(Arrays.toString(hostDataFilled));
+        System.out.println(Arrays.toString(hostData));
+        JCuda.cudaFree(pointer);
+    }
+
+    private static long getPointerAddress(Pointer p)
+    {
+        // WORKAROUND until a method like CUdeviceptr#getAddress exists
+        class PointerWithAddress extends Pointer
+        {
+            PointerWithAddress(Pointer other)
+            {
+                super(other);
+            }
+            long getAddress()
+            {
+                return getNativePointer() + getByteOffset();
+            }
+        }
+        return new PointerWithAddress(p).getAddress();
+    }
+};