Java Adapter

Use Zinc from Java with JNA

The Java adapter uses JNA (Java Native Access) to call the Zinc C ABI. JNA needs no native glue code. It loads the shared library and maps function calls through its built-in FFI.

Installation

Build the core from a source checkout, then run mvn install in adapters/java. This installs the adapter into your local Maven repository; Maven Central publishing is pending. The source targets Java 17 or later. Add the dependency to your application:

<dependency>
    <groupId>dev.zinc</groupId>
    <artifactId>zinc-java</artifactId>
    <version>0.1.0</version>
</dependency>

The adapter requires JNA 5.x, which is pulled in as a transitive dependency.

SharedRegion

import dev.zinc.SharedRegion;

create

var region = SharedRegion.create("my-data", 16384L);

Creates a new region. Throws RuntimeException on failure.

open

var region = SharedRegion.open("my-data");

Opens an existing region.

buffer

Returns a java.nio.ByteBuffer backed by the shared memory mapping. No copying occurs.

var buf = region.buffer();
buf.putFloat(0, 3.14f);
buf.rewind();
float val = buf.getFloat(0);

The buffer is direct (backed by native memory). It is writable by default.

signal

region.signal();

waitForNotification

boolean ok = region.waitForNotification(1000);

Returns true on notification, false on timeout.

close

region.close();

SharedRegion implements AutoCloseable for try-with-resources:

try (var region = SharedRegion.open("my-data")) {
    var buf = region.buffer();
    float val = buf.getFloat(0);
} // region is automatically closed

Complete example

import dev.zinc.SharedRegion;

public class Example {
    public static void main(String[] args) {
        try (var writer = SharedRegion.create("java-channel", 16384);
             var reader = SharedRegion.open("java-channel")) {
            writer.buffer().putDouble(0, 3.14159);
            writer.signal();
            if (reader.waitForNotification(3000)) {
                System.out.println(reader.buffer().getDouble(0));
            }
        }
    }
}

This uses two handles in one JVM. For separate JVMs, keep the creator running until the reader finishes.

tryWait() consumes a pending notification without blocking.

JNA internals

The ZincLib interface maps the C ABI functions:

interface ZincLib extends Library {
    ZincLib INSTANCE = Native.load("zinc_core", ZincLib.class);

    int zinc_create(String name, long capacity, PointerByReference out);
    int zinc_open(String name, PointerByReference out);
    Pointer zinc_ptr(Pointer handle);
    long zinc_capacity(Pointer handle);
    void zinc_close(Pointer handle);
    void zinc_notify(Pointer handle);
    int zinc_wait(Pointer handle, int timeoutMs);
}

JNA loads libzinc_core.{so,dylib} through its platform-native library loading mechanism. Ensure the library is on java.library.path or use Native.load with an absolute path.

The Pointer.getByteBuffer(offset, length) method creates a direct ByteBuffer wrapping the native memory. The JVM garbage collector does not manage this buffer. It is valid only as long as the region handle is open.