diff --git a/ffi/MIGRATE.md b/ffi/MIGRATE.md index 4cd03afe4..ab8ae0f12 100644 --- a/ffi/MIGRATE.md +++ b/ffi/MIGRATE.md @@ -2,12 +2,13 @@ ## Unreleased -- Kotlin returns bytes as a `Bytes`, not a `ByteArray`: Rust's buffer, lent uncopied as - `bytes.buffer`, a read-only direct `ByteBuffer`, until `bytes.close()` frees it. Read it - in `use { }`, or copy it out with `toByteArray()`. A record's bytes field is a `Bytes` - too: build one to pass in with `Bytes(byteArray)`. Arguments stay `ByteArray`. Kotlin's - objects and `Bytes` never closed are freed once the GC collects them, and an exported - type named `bytes` clashes with the runtime's `_bytes`, which takes a `rename`. +- Kotlin returns bytes as a `Bytes`, not a `ByteArray`: Rust's buffer as `bytes.buffer`, a + read-only `ByteBuffer`, copied up to 1 KiB and otherwise a direct one lent uncopied + until `bytes.close()` frees it. Read it in `use { }`, or copy it out with + `toByteArray()`. A record's bytes field is a `Bytes` too: build one to pass in with + `Bytes(byteArray)`. Arguments stay `ByteArray`. Kotlin's objects and `Bytes` never + closed are freed once the GC collects them, and an exported type named `bytes` clashes + with the runtime's `_bytes`, which takes a `rename`. - A type parameter bounded by serde's `Serialize` or `Deserialize` takes `serde_json::Value`, not `String`: C passes a `_json` it parses from JSON text with `_json_parse`, not a buffer, and a generic type at such a parameter is diff --git a/ffi/README.md b/ffi/README.md index eedc1e8f2..541c2bb99 100644 --- a/ffi/README.md +++ b/ffi/README.md @@ -237,9 +237,11 @@ in as a `ByteArray`, bytes returned as their owner, and anything else encoded in or for one with data a sealed class of a data class per variant. `Display` is `toString()`, `Debug` `debug()`, and `Default` a companion's `default()`. - **Bytes** passed in are a `ByteArray`, copied, as are those Rust lends a closure or trait - method. Bytes Rust returns, or a record holds, are a `Bytes`, which lends Rust's buffer - as a read-only direct `ByteBuffer` until `close()` frees it, or, never closed, until the - GC collects that buffer; `Bytes(ByteArray)` holds Kotlin's for a record passed in. + method. Bytes Rust returns, or a record holds, are a `Bytes`, a read-only `ByteBuffer`: + up to 1 KiB copied, and longer ones lending Rust's buffer as a direct one until `close()` + frees it, or, never closed, until the GC collects that buffer, since a copy undercuts + `NewDirectByteBuffer` only that far; `Bytes(ByteArray)` holds Kotlin's for a record + passed in. Strings are `String`, `Option` `T?`, a tuple `Pair`, `Triple`, or past them a generated `Tuple`, `Duration` `kotlin.time.Duration`, and an `Err` a thrown `Exception` holding it, whose message is its `Display`. diff --git a/ffi/fixtures/api/src/lib.rs b/ffi/fixtures/api/src/lib.rs index b42f8592f..f79953c0a 100644 --- a/ffi/fixtures/api/src/lib.rs +++ b/ffi/fixtures/api/src/lib.rs @@ -534,10 +534,10 @@ impl Drop for Token { } } -/// Bytes whose drop counts in [`dropped`], as a token's does. -pub fn token_bytes(id: u32) -> Bytes { +/// `len` bytes of `id`'s low byte, whose drop counts in [`dropped`], as a token's does. +pub fn token_bytes(id: u32, len: u32) -> Bytes { // The token is held only for its drop. - struct Owner(#[allow(dead_code)] Token, [u8; 4]); + struct Owner(#[allow(dead_code)] Token, Vec); impl AsRef<[u8]> for Owner { fn as_ref(&self) -> &[u8] { @@ -545,7 +545,7 @@ pub fn token_bytes(id: u32) -> Bytes { } } - Bytes::from_owner(Owner(Token::new(id), id.to_le_bytes())) + Bytes::from_owner(Owner(Token::new(id), vec![id as u8; len as usize])) } /// A payload and its sequence number: a record, whose bytes cross in both ways. diff --git a/ffi/runtime/jni.rs b/ffi/runtime/jni.rs index 62c72e0f8..24aa8832f 100644 --- a/ffi/runtime/jni.rs +++ b/ffi/runtime/jni.rs @@ -4,8 +4,9 @@ //! A value Kotlin passes is a JNI scalar, a handle as a `long`, its bytes as a `byte[]`, //! or anything else encoded into a `byte[]`: little-endian, field by field, as the C //! struct holds it, with a buffer as its length (-1 for none) and its bytes, and an array -//! as its length (-1 for none) and its elements. Bytes Rust returns cross as their owner, -//! which a Kotlin `Bytes` lends as a direct `ByteBuffer` until it frees it. +//! as its length (-1 for none) and its elements. Bytes Rust returns cross copied when short, +//! and otherwise as their owner, which a Kotlin `Bytes` lends as a direct `ByteBuffer` +//! until it frees it. use std::cell::Cell; use std::ffi::{CStr, c_void}; @@ -160,15 +161,48 @@ pub fn array(env: *mut JNIEnv, bytes: &[u8]) -> jbyteArray { } } -/// The owner of a buffer Rust returned, handed to Kotlin uncopied, or 0 for none: a view, -/// which Rust lent only for a call, is copied into an owned buffer. +/// The longest bytes Rust returns that cross copied, freed at once: a lent `ByteBuffer` +/// costs `NewDirectByteBuffer`'s upcall and a cleaner registration, which copying up to +/// about this many bytes undercuts. +const COPIED: usize = 1024; + +/// A buffer Rust returned or lent, as Kotlin's `Native.owned` takes it: null for none, a +/// `byte[]` copy of up to [`COPIED`] bytes, freeing the buffer, or else a `long[]` holding +/// the owner it lends them through. /// /// # Safety /// `buf` is a buffer Rust returned or lent, freed by nothing else. -pub unsafe fn hand(buf: rt::Buf) -> jlong { +pub unsafe fn hand(env: *mut JNIEnv, buf: rt::Buf) -> jobject { if buf.is_none() { - return 0; + return std::ptr::null_mut(); + } + if buf.len <= COPIED { + // SAFETY: the caller's contract. + return unsafe { + let array = array(env, buf.bytes("jni")); + buf.free(); + array + }; + } + // SAFETY: the caller's contract. + let owner = unsafe { self::owner(buf) }; + // SAFETY: `env` is this thread's. + unsafe { + let array = ((**env).v1_2.NewLongArray)(env, 1); + if array.is_null() { + fail(env, "jni", "a long[] is out of memory"); + } + ((**env).v1_2.SetLongArrayRegion)(env, array, 0, 1, &owner); + array } +} + +/// The owner of a buffer Rust returned, handed to Kotlin uncopied: a view, which Rust lent +/// only for a call, is copied into an owned buffer. +/// +/// # Safety +/// `buf` is a buffer Rust returned or lent, not none, and freed by nothing else. +unsafe fn owner(buf: rt::Buf) -> jlong { let buf = match buf.owner.is_null() { // SAFETY: the caller's contract. true => rt::Buf::owned(bytes::Bytes::copy_from_slice(unsafe { buf.bytes("jni") })), @@ -571,18 +605,35 @@ impl Wire for rt::Buf { } } -/// Bytes Rust returns, or an array of them, crossing as each buffer's owner rather than -/// copied: see [`hand`]. +/// Bytes Rust returns, or an array of them, each crossing as [`hand`] hands it over. pub struct Owned(pub T); +/// What precedes a lent buffer's owner where an encoded one's length would. +const LENT: i32 = -2; + impl Wire for Owned { fn read(_: &mut Reader<'_>) -> Self { rt::fail("jni", "Kotlin passes bytes, never their owner") } + // None as -1, bytes up to [`COPIED`] long as their length and a copy, and longer ones as + // [`LENT`] and their owner. fn write(self, w: &mut Writer) { - // SAFETY: a buffer Rust returned or lent, handed over here. - w.put(unsafe { hand(self.0) }); + let buf = self.0; + if buf.is_none() { + w.put(-1i32); + } else if buf.len <= COPIED { + w.put(buf.len as i32); + // SAFETY: a buffer Rust returned or lent, freed here once copied. + unsafe { + w.0.extend_from_slice(buf.bytes("jni")); + buf.free(); + } + } else { + w.put(LENT); + // SAFETY: a buffer Rust returned or lent, handed over here. + w.put(unsafe { owner(buf) }); + } } } diff --git a/ffi/runtime/rt.kt b/ffi/runtime/rt.kt index 3af9461e1..eb69cf20e 100644 --- a/ffi/runtime/rt.kt +++ b/ffi/runtime/rt.kt @@ -160,8 +160,12 @@ class Reader(bytes: ByteArray) { return v } - /** Bytes Rust handed over uncopied, as their owner, or null for none. */ - fun owned(): Bytes? = b.getLong().let { if (it == 0L) null else Bytes(it) } + /** Bytes Rust handed over, copied or lent by their owner, or null for none. */ + fun owned(): Bytes? = when (val n = b.getInt()) { + -1 -> null + LENT -> Bytes(b.getLong()) + else -> Bytes(ByteArray(n).also { b.get(it) }) + } fun string(): String? { val n = b.getInt() @@ -323,6 +327,16 @@ class Free(buffer: java.nio.ByteBuffer, private val owner: Long) : Cleanup(buffe override fun collected() = free() } +/** What precedes a lent buffer's owner where an encoded one's length would. */ +const val LENT = -2 + +/** Bytes a call returned: copied, lent by the owner a `LongArray` holds, or null for none. */ +fun owned(given: Any?): Bytes? = when (given) { + null -> null + is ByteArray -> Bytes(given) + else -> Bytes((given as kotlin.LongArray)[0]) +} + /** Run [block] with the raw handle of [handle], or 0 for none, held until it returns. */ inline fun hold(handle: Handle?, block: (Long) -> R): R = when (handle) { null -> block(0L) diff --git a/ffi/src/kotlin.rs b/ffi/src/kotlin.rs index 17c30c725..1bee7f431 100644 --- a/ffi/src/kotlin.rs +++ b/ffi/src/kotlin.rs @@ -125,11 +125,12 @@ pub fn generate(abi: &Abi<'_>, packages: &str, contract: u64) -> Result e.to_string(), (None, false, true) => format!("{e}!!"), - (None, true, false) => format!("{e}.let {{ o -> if (o == 0L) null else Bytes(o) }}"), - (None, false, false) => format!("Bytes({e})"), + (None, true, false) => format!("Native.owned({e})"), + (None, false, false) => format!("Native.owned({e})!!"), }, _ => { let r = self.fresh("r"); @@ -1564,8 +1565,8 @@ impl<'a> Gen<'a> { } else { let c_ret = export.call.ret.clone(); let (jni, native) = match c_ret { - // Bytes cross as their owner. - Ty::Buf if !string(&ok) => ("jlong", "Long"), + // Bytes cross copied or as their owner. + Ty::Buf if !string(&ok) => ("jobject", "Any?"), _ => jni_type(&c_ret, &ok), }; let params: Vec<(&str, &str)> = native_params.iter().map(|(j, k)| (*j, k.as_str())).collect(); @@ -1578,7 +1579,7 @@ impl<'a> Gen<'a> { Ty::Enum(_) => "ret".to_string(), Ty::Handle { .. } => "ret as usize as jlong".to_string(), Ty::Buf if string(&ok) => "rt::owned(env, ret)".to_string(), - Ty::Buf => "rt::hand(ret)".to_string(), + Ty::Buf => "rt::hand(env, ret)".to_string(), _ => format!( "{{ let mut w = rt::Writer::default(); {}; w.array(env) }}", put(&ok, "ret") diff --git a/ffi/tests/api.kt b/ffi/tests/api.kt index a96f7dcd8..5bebb2555 100644 --- a/ffi/tests/api.kt +++ b/ffi/tests/api.kt @@ -490,16 +490,31 @@ fun broken(which: String) { } // What frees an object or bytes nobody closed: the GC, once each is collected, and only -// what closing did not free already. +// what closing did not free already. Rust's bytes up to 1 KiB cross copied, freed at the +// call, and longer ones lent until closed or collected. fun owned() { - val packet = nextPacket(Packet(1u, Bytes("seq".encodeToByteArray()))) - check(packet.seq == 2u && packet.payload.text() == "seq", "a record's bytes cross both ways") - val read = tokenBytes(0u).also { it.close() } - check(runCatching { read.toByteArray() }.isFailure, "closed bytes refuse a read") + for (n in 1023..1025) { + val payload = ByteArray(n) { it.toByte() } + val packet = nextPacket(Packet(1u, Bytes(payload))) + check(packet.seq == 2u && packet.payload.use { it.toByteArray() }.contentEquals(payload), "a record's $n bytes cross both ways") + } + var freed = dropped() + for (n in 1023u..1025u) { + val bytes = tokenBytes(n, n) + if (n <= 1024u) freed++ + check(dropped() == freed, "$n bytes are freed at the call only if copied") + check(bytes.toByteArray().contentEquals(ByteArray(n.toInt()) { n.toByte() }), "$n bytes read back") + bytes.close() + if (n > 1024u) freed++ + check(dropped() == freed, "closing $n bytes frees them") + bytes.close() + check(dropped() == freed, "closing $n bytes again frees nothing") + check(runCatching { bytes.toByteArray() }.isFailure, "closed $n bytes refuse a read") + } val before = dropped() Token.new(1u).close() - tokenBytes(2u).close() + tokenBytes(2u, 1025u).close() check(dropped() == before + 2u, "closing frees at once") unclosed() val deadline = System.nanoTime() + 10.seconds.inWholeNanoseconds @@ -512,10 +527,11 @@ fun owned() { check(dropped() == before + 4u, "the GC frees each once") } -// In its own frame, so nothing on the caller's keeps them reachable. +// In its own frame, so nothing on the caller's keeps them reachable. The bytes are long +// enough to be lent. fun unclosed() { Token.new(3u) - tokenBytes(4u) + tokenBytes(4u, 1025u) } fun main(args: Array) { diff --git a/quest/m1/ffi-export/README.md b/quest/m1/ffi-export/README.md index c48a608d0..d02640ecf 100644 --- a/quest/m1/ffi-export/README.md +++ b/quest/m1/ffi-export/README.md @@ -52,4 +52,3 @@ Every generator on the C ABI: - [Tuples inside other types](/quest/m1/ffi-export/tuples.md) - a tuple crosses as an iterator's or `Vec`'s item, in an `Option`, or as a field, so hang's `ranked` exports - [C++ bindings on MSVC and Clang](/quest/m1/ffi-export/cpp.md) - the C++ header built and tested beyond GCC on Linux - [Kotlin bindings on Android](/quest/m1/ffi-export/kotlin-android.md) - an R8 keep rule for JNI's lookups, and an emulator run in CI -- [Kotlin payload reads at JNI's cost](/quest/m1/ffi-export/kotlin-reads.md) - a Kotlin payload read stops paying `NewDirectByteBuffer`'s ~100 ns, if the maintainer lets `Bytes` copy diff --git a/quest/m1/ffi-export/kotlin-reads.md b/quest/m1/ffi-export/kotlin-reads.md deleted file mode 100644 index 6c253de1a..000000000 --- a/quest/m1/ffi-export/kotlin-reads.md +++ /dev/null @@ -1,33 +0,0 @@ -# [M] Kotlin payload reads at JNI's cost - -## Goal - -A payload read through the generated Kotlin costs what its JNI crossings must: -`just ffi bench`'s "payload read" line closes most of its gap to C, each cut measured. After -[#231](https://github.com/moq-dev/rust2/pull/231), Kotlin takes 147-176 ns per 100 B -payload read against C's 15-16. - -The semantics stay as they are: `close()` is idempotent and frees exactly once, and the GC -frees what nobody closed. The maintainer decides whether `Bytes` may copy. - -## Plan - -An async-profiler profile of payload reads alone, in #231, puts about 60% of the time in -`NewDirectByteBuffer`: HotSpot builds the buffer through an upcall into its constructor, -and no public API wraps a native address more cheaply before JDK 22's FFM, which Android -lacks. The `Free` registration, `asReadOnlyBuffer`, and the free crossing take most of the -rest. - -A prototype that copied payloads up to 1 KiB into a heap `ByteArray`, freeing the Rust -bytes in the same crossing and registering nothing with the cleaner, measured 68 ns. Its -remaining cost was `NewByteArray` and `SetByteArrayRegion`. Open question for the -maintainer: copy below a threshold and lend above it, keep lending always, or always copy. -Folding the copy into the getter's own crossing would cut one more. - -A ready result still crosses as a new `byte[]` from `NewByteArray`. A thread-local direct -buffer that Rust writes and Kotlin reads would drop it, at the cost of a reentrancy rule: -nothing may cross on that thread until the result is read. - -## Related - -- [Kotlin bindings on Android](/quest/m1/ffi-export/kotlin-android.md) - whatever replaces the buffers must hold on ART too