Aller au contenu

Quickstart - consuming kffi end to end

This guide covers Gradle dependency setup, memoryScope, allocation, write/read, CString, lifetime, the unsafe option, a simple callback, and loading a native library. All symbols used here belong to the public org.graphiks.kffi API (see the README for the complete contract).

1. Dependency

The group is org.graphiks. Release artifacts are consumed from Maven Central. Development snapshots default to 1.0.0-SNAPSHOT and can be consumed from the Central Portal snapshot repository:

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        mavenCentral()
        maven {
            name = "CentralPortalSnapshots"
            url = uri("https://central.sonatype.com/repository/maven-snapshots/")
            content {
                includeGroup("org.graphiks")
            }
        }
    }
}

The dependency snippets use 1.0.0-SNAPSHOT by default; replace it with an explicitly selected published version when consuming a release. Gradle publication version selection uses the releaseVersion property, set with -PreleaseVersion=...; without an explicit value, it defaults to 1.0.0-SNAPSHOT. The canonical root publication workflow selects the version from workflow dispatch input or a release tag and publishes through the single aggregated ./gradlew publishToMavenCentral task.

// build.gradle.kts - KMP project; the root artifact resolves the platform variant
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("org.graphiks.kffi:kffi:1.0.0-SNAPSHOT") // or an explicitly selected published version
        }
    }
}

JVM-only project: implementation("org.graphiks.kffi:kffi-jvm:1.0.0-SNAPSHOT") (JDK 25+ for java.lang.foreign).

Android project: implementation("org.graphiks.kffi:kffi-android:1.0.0-SNAPSHOT") (minSdk 28).

Native project: the root artifact org.graphiks.kffi:kffi is sufficient; Gradle resolves the kffi-<target> variant (for example, kffi-macosarm64). There is no aggregate kffi-native artifact.

2. memoryScope, allocation, write/read

memoryScope { } creates an allocator scope and guarantees that it is closed at the end of the block (equivalent to use { }). On the JVM, that scope is a confined arena:

import org.graphiks.kffi.*

memoryScope { allocator ->
    val buffer = allocator.allocateBuffer(size = 16uL)

    buffer.writeInt(value = 42, offset = 0uL)
    check(buffer.readInt(offset = 0uL) == 42)

    buffer.writeLong(value = 0xCAFEL, offset = 8uL)
    check(buffer.readLong(offset = 8uL) == 0xCAFEL)

    // Bounds checks are enabled by default: any access outside `size` throws
    // IndexOutOfBoundsException (the message includes offset/width/size).
    buffer.readLong(offset = 12uL)
    // IndexOutOfBoundsException: MemoryBuffer access out of bounds: offset=12 width=8 size=16
}
// allocator.close() is guaranteed here; every buffer from this scope is invalid.

3. Arrays and strings

memoryScope { allocator ->
    val buffer = allocator.allocateBuffer(size = 32uL)

    // Arrays: starting index in the array plus offset in the buffer
    val out = IntArray(4)
    buffer.writeInts(intArrayOf(1, 2, 3, 4), bufferOffset = 0uL)
    buffer.readInts(out, bufferOffset = 0uL)
    check(out.contentEquals(intArrayOf(1, 2, 3, 4)))

    // Strings: allocate a UTF-8 C string terminated by \0 from the scope
    val cstr = allocator.allocateFrom("hello")
    check(cstr.toKString() == "hello")
}

4. Lifetime

The arena scope lives in MemoryBuffer (decision I2-a):

  • On the JVM, a buffer from MemoryAllocator throws IllegalStateException after close().
  • On Android and Native, closing MemoryAllocator releases its arena without a per-buffer close guard; accessing allocator-backed memory afterward is undefined behavior.
  • A buffer created from a raw address has no guard. Access after the memory is released is undefined behavior on JVM, Android, and Native.
val allocator = MemoryAllocator()
val scoped = allocator.allocateBuffer(16uL)
allocator.close()
// JVM-only pseudocode (not executed): scoped.writeLong(1L, 0uL)
// -> throws IllegalStateException: "MemoryBuffer has been closed"
// Android/Native: never execute the post-close access; it is undefined behavior.

// A raw-address buffer has no scope or guard; using freed memory is documented UB.
val backing = MemoryAllocator()
val raw = MemoryBuffer(backing.allocate(16L), 16uL) // alive while backing is open
raw.writeLong(7L, 0uL)

// Process-lifetime arena
val forever = globalMemory.allocateBuffer(16uL)

Two buffers over the same memory area see each other's writes; no synchronization is provided.

JVM only: the arena is confined to the creating thread (Arena.ofConfined()): access to scoped buffers and close() from another thread throws WrongThreadException; memoryScope follows the same rule. In unsafe mode, access uses the raw address, so there is no thread check and the JVM close guard still applies. Raw-address buffers have no confinement (null guard, documented UB).

Android/Native: this JVM confinement rule does not apply. Android uses the runtime unsafe flag, while Native uses the compile-time policy described in the next section.

5. unsafe option

JVM and Android: unsafe = true is a runtime option. It can be enabled per allocator (propagating to every buffer in the arena) or per buffer:

// Per allocator: every created buffer is unsafe
val hotAllocator = MemoryAllocator(unsafe = true)
val hot = hotAllocator.allocateBuffer(128uL)
hot.writeLong(1L, 64uL) // within the 128-byte allocation

// Per buffer: local opt-in. The backing allocation is 128 bytes, while the
// nominal MemoryBuffer view is 64 bytes.
memoryScope { allocator ->
    val localUnsafe = MemoryBuffer(allocator.allocate(128L), 64uL, unsafe = true)
    // JVM/Android: outside the nominal view, but inside the 128-byte backing
    // allocation. Bounds checks are intentionally skipped for this access.
    localUnsafe.writeLong(1L, 96uL)
}

hotAllocator.close()
// JVM-only pseudocode (not executed): hot.writeLong(2L, 0uL)
// -> throws IllegalStateException; the lifetime guard remains in unsafe mode.
// Android: never execute the post-close access; it is undefined behavior.

Unsafe policy P2: on JVM and Android, unsafe skips only runtime bounds checks. Lifetime discipline is unchanged: using a buffer after its arena closes remains forbidden (use-after-free). The backing allocations above are large enough for the demonstrated offsets; the per-buffer example is outside only the nominal 64-byte view.

Native: the runtime unsafe argument is ignored. The value is fixed at compile time by KFFI_NATIVE_UNSAFE in MemoryBuffer.native.kt, currently false by default. Consequently, current Native builds keep bounds checks enabled: the offset = 96uL call in the example would throw IndexOutOfBoundsException. To change that policy, edit the constant and rebuild the module.

6. Simple callback (Native upcall to Kotlin)

Code generated by kextract provides the descriptors, trampolines, and dispatchers; the following shows the same mechanism by hand. A callback first implements the Callback marker interface. The trampoline below is the JVM-specific form using JvmUpcallEngine; Android uses its UpcallEngine variant with explicit JNI management:

import org.graphiks.kffi.Callback
import org.graphiks.kffi.CallbackExceptionHandler
import org.graphiks.kffi.CallbackPolicy
import org.graphiks.kffi.CallbackRuntime
import org.graphiks.kffi.CallbackRuntimeApi
import org.graphiks.kffi.CallbackType
import org.graphiks.kffi.NativeAddress
import org.graphiks.kffi.engine.UpcallEngine
import org.graphiks.kffi.engine.JvmUpcallEngine

@OptIn(CallbackRuntimeApi::class)
private fun interface StatusCallback : Callback {
    fun onStatus(value: Int)
}

The trampoline is a Native stub that calls a static dispatcher. The dispatcher routes to the lambda registered through CallbackRuntime.dispatchSafely (userdata is the routing token and the last C parameter):

@OptIn(CallbackRuntimeApi::class)
private object StatusTrampolines {
    val type = CallbackType<StatusCallback>("quickstart-status", hasRoutingUserdata = true)

    val stub: NativeAddress by lazy {
        JvmUpcallEngine.allocateTrampoline(
            dispatcherClass = StatusTrampolines::class.java,
            dispatchMethod = "dispatch",
            dispatchSig = "(IJ)V", // (int value, long routingUserdata) -> void
        )
    }

    @JvmStatic
    fun dispatch(value: Int, userdata: Long) {
        CallbackRuntime.dispatchSafely(
            type,
            userdata.takeIf { it != 0L }?.let(::NativeAddress),
        ) { it.onStatus(value) }
    }
}

Registration exposes the trampoline address (callback) and routing token (userdata) for the Native library:

@OptIn(CallbackRuntimeApi::class)
fun installStatusCallback() {
    val registration = CallbackRuntime.register(
        type = StatusTrampolines.type,
        trampoline = StatusTrampolines.stub,
        policy = CallbackPolicy.REPEATING,
        onError = CallbackExceptionHandler { error -> println("callback failed: $error") },
        callback = StatusCallback { value -> println("native called us with $value") },
    )

    // The Native library receives the trampoline address and userdata.
    // nativeCallExpectsCallback(registration.callback, registration.userdata)

    // Closing prevents further delivery; isQuiescent becomes true after
    // in-flight Native calls return. On Android, unregister the callback from
    // the C library, stop and join every native callback producer, and only
    // then call UpcallEngine.freeTrampoline(...). isQuiescent alone cannot see
    // a native callback that has not entered the Kotlin dispatcher yet.
    registration.close()
    check(registration.isClosed)
}

On Android, generated callback code uses the four-argument trampoline API:

@OptIn(CallbackRuntimeApi::class)
private object StringStatusTrampolines {
    val type = CallbackType<StatusCallback>("quickstart-string-status", hasRoutingUserdata = true)

    val stub: NativeAddress by lazy {
        NativeAddress(
            UpcallEngine.allocateTrampoline(
                dispatcherClass = StringStatusTrampolines::class.java,
                dispatchMethod = "dispatch",
                dispatchJvmSignature = "(JJI)V",
                dispatchAbiSignature = "v(struct(ptr,size_t),u32,ptr)",
            )
        )
    }

    @JvmStatic
    fun dispatch(routingToken: Long, messageAddress: Long, status: Int) {
        // messageAddress is valid only while this dispatcher is running.
        // Copy the WGPUStringView fields immediately if you need to retain them.
        CallbackRuntime.dispatchSafely(
            type,
            routingToken.takeIf { it != 0L }?.let(::NativeAddress),
        ) { callback ->
            callback.onStatus(status)
        }
    }
}

dispatchJvmSignature = "(JJI)V" describes the JNI dispatcher shape: routingToken (J), messageAddress (J), and status (I). The ABI signature dispatchAbiSignature = "v(struct(ptr,size_t),u32,ptr)" describes the C callback shape void (WGPUStringView, uint32_t, void*). The final ptr is routing userdata; the WGPUStringView argument arrives as a temporary address that must be copied immediately during dispatch.

Contract points:

  • close() removes the slot (the token is never reused); isQuiescent becomes true only after route removal and all in-flight deliveries return.
  • onQuiescent { ... } runs each action exactly once after closure and the last admitted delivery; registration after quiescence invokes the action immediately.
  • ONCE is unpublished after the first delivery; REPEATING remains active until close().
  • No exception crosses the Native boundary; failures are routed to onError or the fallback channel. The result-returning dispatchSafely overload returns its caller-provided default value on failure.
  • On the JVM, stubs are allocated in a global process-lifetime arena. On Android, UpcallEngine.allocateTrampoline / freeTrampoline provide explicit JNI management (generated by kextract). Before freeTrampoline, generated or native code must unregister the callback from the C library, stop and join every native callback producer, and only then free the closure; a registration being isQuiescent does not prove that native code has stopped racing toward the trampoline.

7. Loading a native library

JVM - load the library into the process, then resolve its symbols:

System.loadLibrary searches java.library.path, not the classpath. If a library is packaged as a classpath resource, extract it to an absolute file first and load it with System.load(extractedAbsolutePath).

import org.graphiks.kffi.findOrThrow

System.loadLibrary("monlib")

val fn = findOrThrow("mon_symbole") // UnsatisfiedLinkError if not found

Start the JVM with --enable-native-access=ALL-UNNAMED: the JVM kffi runtime uses restricted java.lang.foreign APIs itself, and kextract bindings can emit upcalls on the direct FFM path. Without the flag, the JVM emits a warning and will block the call in a future JDK version.

Android - the libkffi.so engine loads automatically; the consumed library is loaded with dlopen:

import org.graphiks.kffi.engine.NativeEngine

val pathToLib = "/data/app/.../libmonlib.so"
val handle = NativeEngine.loadNativeLibrary(pathToLib) // dlopen RTLD_NOW|RTLD_GLOBAL
val fn = NativeEngine.resolveSymbolIn(handle, "mon_symbole")

Native - linking happens at compile time through cinterop (.def); no dynamic loading is required.

8. Generating bindings

kffi is runtime-only: generate bindings with kextract, targeting org.graphiks.kffi, then link them to kffi as described above. Generated bindings use the same primitives as this guide (MemoryBuffer, MemoryAllocator, CallbackRuntime, and the backend engines).