Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions ffi/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<prefix>_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 `<prefix>_bytes`, which takes a `rename`.
- A type parameter bounded by serde's `Serialize` or `Deserialize` takes
`serde_json::Value`, not `String`: C passes a `<prefix>_json` it parses from JSON text
with `<prefix>_json_parse`, not a buffer, and a generic type at such a parameter is
Expand Down
8 changes: 5 additions & 3 deletions ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>` `T?`, a tuple `Pair`,
`Triple`, or past them a generated `Tuple<n>`, `Duration` `kotlin.time.Duration`, and an `Err` a thrown `<E>Exception`
holding it, whose message is its `Display`.
Expand Down
8 changes: 4 additions & 4 deletions ffi/fixtures/api/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -534,18 +534,18 @@ 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<u8>);

impl AsRef<[u8]> for Owner {
fn as_ref(&self) -> &[u8] {
&self.1
}
}

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.
Expand Down
71 changes: 61 additions & 10 deletions ffi/runtime/jni.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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};
Expand Down Expand Up @@ -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") })),
Expand Down Expand Up @@ -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<T>(pub T);

/// What precedes a lent buffer's owner where an encoded one's length would.
const LENT: i32 = -2;

impl Wire for Owned<rt::Buf> {
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) });
}
}
}

Expand Down
18 changes: 16 additions & 2 deletions ffi/runtime/rt.kt
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down Expand Up @@ -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 <R> hold(handle: Handle?, block: (Long) -> R): R = when (handle) {
null -> block(0L)
Expand Down
19 changes: 10 additions & 9 deletions ffi/src/kotlin.rs
Original file line number Diff line number Diff line change
Expand Up @@ -125,11 +125,12 @@ pub fn generate(abi: &Abi<'_>, packages: &str, contract: u64) -> Result<Output,

const IMPORTS: &[&str] = &["kotlin.coroutines.resume", "kotlin.time.toDuration"];

/// The bytes Rust returns, lent rather than copied.
/// The bytes Rust returns, copied when short and otherwise lent.
const BYTES: &str = "/**
* Bytes Rust returned, lent without a copy: [buffer] reads them until [close] frees them,
* after which reading it is undefined. Unclosed, they are freed once the GC collects
* [buffer], so keep it, not only a slice or duplicate of it, while reading.
* Bytes Rust returned: up to 1 KiB copied, and longer ones lent without a copy, which
* [buffer] reads until [close] frees them, after which reading it is undefined. Unclosed,
* lent ones are freed once the GC collects [buffer], so keep it, not only a slice or
* duplicate of it, while reading.
*/
class Bytes private constructor(buffer: java.nio.ByteBuffer, owner: Long) : AutoCloseable {
\t/** Bytes Kotlin holds, as a record Rust takes needs, which [close] leaves readable. */
Expand Down Expand Up @@ -492,8 +493,8 @@ impl<'a> Gen<'a> {
(Some(decode), false, _) => format!("{e}!!.{decode}"),
(None, true, true) => 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");
Expand Down Expand Up @@ -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();
Expand All @@ -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")
Expand Down
32 changes: 24 additions & 8 deletions ffi/tests/api.kt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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<String>) {
Expand Down
1 change: 0 additions & 1 deletion quest/m1/ffi-export/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
33 changes: 0 additions & 33 deletions quest/m1/ffi-export/kotlin-reads.md

This file was deleted.