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
MemoryAllocatorthrowsIllegalStateExceptionafterclose(). - On Android and Native, closing
MemoryAllocatorreleases 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);isQuiescentbecomes 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.ONCEis unpublished after the first delivery;REPEATINGremains active untilclose().- No exception crosses the Native boundary; failures are routed to
onErroror the fallback channel. The result-returningdispatchSafelyoverload returns its caller-provided default value on failure. - On the JVM, stubs are allocated in a global process-lifetime arena. On
Android,
UpcallEngine.allocateTrampoline/freeTrampolineprovide explicit JNI management (generated by kextract). BeforefreeTrampoline, 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 beingisQuiescentdoes 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).