//! The runtime the Kotlin glue's JNI functions share: the codec values cross in, the //! thread a call into Kotlin runs on, and the wakers a Kotlin future parks on. //! //! A value Kotlin passes is a JNI scalar, a handle as a `long`, its bytes as a `byte[]`, //! or composite returns constructed by a Kotlin factory over scoped native memory. //! The codec (also used for parameters) is 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; a record passed or returned directly //! crosses its scalars as parameters, or through Kotlin's `long[]` slots, apart from the //! rest. Bytes Rust returns cross copied when short, //! and otherwise as their owner, which a Kotlin `Bytes` reads through a call each until the //! GC collects it. use std::cell::Cell; use std::ffi::{CStr, c_void}; use std::mem::MaybeUninit; use std::sync::OnceLock; use std::sync::atomic::{AtomicUsize, Ordering}; pub use jni_sys::*; use crate::rt; /// The JVM, and the global reference to the class holding the native methods and the /// Kotlin functions Rust calls, set by the class's first native call. static VM: OnceLock = OnceLock::new(); static CLASS: OnceLock = OnceLock::new(); /// Note the JVM and `class`, from its first native call, which its initializer makes. The /// library defines no `JNI_OnLoad`, so the crate it exports may define its own. /// /// # Safety /// `env` is this thread's, and `class` the native class. pub unsafe fn load(env: *mut JNIEnv, class: jclass) { // SAFETY: `env` is this thread's, as the caller's contract says. unsafe { let mut vm: *mut JavaVM = std::ptr::null_mut(); if ((**env).v1_2.GetJavaVM)(env, &mut vm) != JNI_OK { fail(env, "load", "the JVM is missing"); } let _ = VM.set(vm as usize); CLASS.get_or_init(|| ((**env).v1_2.NewGlobalRef)(env, class) as usize); // JNI permits a VM without direct-buffer access. Refuse it while loading, // before a call can hand over values that its return factory cannot read. let mut probe = 0u8; let buffer = ((**env).v1_4.NewDirectByteBuffer)(env, (&mut probe as *mut u8).cast(), 1); if buffer.is_null() { fail(env, "load", "the JVM does not support native return buffers"); } ((**env).v1_2.DeleteLocalRef)(env, buffer); } } /// The class holding the Kotlin functions Rust calls. pub fn class() -> jclass { *CLASS.get().expect("the library is loaded") as jclass } thread_local! { /// Whether Rust attached this thread, so it detaches when the thread exits. static ATTACHED: Attached = const { Attached(Cell::new(false)) }; } struct Attached(Cell); impl Drop for Attached { fn drop(&mut self) { if self.0.get() { let vm = *VM.get().expect("attached") as *mut JavaVM; // SAFETY: this thread attached itself, and nothing on it calls Kotlin now. unsafe { ((**vm).v1_4.DetachCurrentThread)(vm) }; } } } /// This thread's JNI environment, attaching it as a daemon until it exits if the JVM /// does not know it, as a thread Rust spawned. pub fn env() -> *mut JNIEnv { let vm = *VM.get().expect("the library is loaded") as *mut JavaVM; let mut env: *mut c_void = std::ptr::null_mut(); // SAFETY: `vm` is the JVM, which outlives every thread calling into it. unsafe { if ((**vm).v1_4.GetEnv)(vm, &mut env, JNI_VERSION_1_6) == JNI_OK { return env.cast(); } if ((**vm).v1_4.AttachCurrentThreadAsDaemon)(vm, &mut env, std::ptr::null_mut()) != JNI_OK { rt::fail("jni", "a thread cannot attach to the JVM"); } } ATTACHED.with(|attached| attached.0.set(true)); env.cast() } /// Whether the Rust a native method called left a Java exception pending, which the /// native method then returns with, unread, for Kotlin to throw, as any native method's /// caller would. pub fn pending(env: *mut JNIEnv) -> bool { // SAFETY: `env` is this thread's. unsafe { ((**env).v1_2.ExceptionCheck)(env) } } /// Abort for `what`, printing the Kotlin exception pending, if any. pub fn fail(env: *mut JNIEnv, what: &str, msg: &str) -> ! { // SAFETY: `env` is this thread's. unsafe { if ((**env).v1_2.ExceptionCheck)(env) { ((**env).v1_2.ExceptionDescribe)(env); } } rt::fail(what, msg) } static REFUSED: OnceLock = OnceLock::new(); /// Throw the `_Native.__Refused`, an `IllegalStateException`, a call of `what` raises once /// its check failed with `status`, returning a zeroed value Kotlin never reads, as JNI's /// pending exception throws once the native method returns. Its own class tells Kotlin /// the call moved nothing. #[cold] pub fn refuse(env: *mut JNIEnv, status: i32, what: &str) -> R { let message = match rt::Status::of(status) { Some(status) => format!("{what}: {}", status.message()), None => format!("{what}: an unknown status {status}"), }; let message = std::ffi::CString::new(message).expect("no NUL in a message"); let id = method(env, &REFUSED, c"__refused", c"(Ljava/lang/String;)Ljava/lang/Throwable;"); // SAFETY: `env` is this thread's, and `__refused` takes the message. unsafe { let text = ((**env).v1_2.NewStringUTF)(env, message.as_ptr()); if text.is_null() { fail(env, what, "a message did not fit"); } let args = [jvalue { l: text }]; let refused = ((**env).v1_2.CallStaticObjectMethodA)(env, class(), id, args.as_ptr()); if refused.is_null() || ((**env).v1_2.ExceptionCheck)(env) { fail(env, what, "a call into Kotlin threw"); } ((**env).v1_2.Throw)(env, refused); std::mem::zeroed() } } static INVALID: OnceLock = OnceLock::new(); /// Throw the `_Native.__Invalid`, an `IllegalArgumentException`, an argument holding a /// value its Rust type cannot raises, which the native method then returns with, as /// [`raised`] does. Its own class tells Kotlin the call moved nothing. #[cold] fn invalid(env: *mut JNIEnv, message: &CStr) { let id = method(env, &INVALID, c"__invalid", c"(Ljava/lang/String;)Ljava/lang/Throwable;"); // SAFETY: `env` is this thread's, and `__invalid` takes the message. unsafe { let text = ((**env).v1_2.NewStringUTF)(env, message.as_ptr()); if text.is_null() { fail(env, "jni", "a message did not fit"); } let args = [jvalue { l: text }]; let invalid = ((**env).v1_2.CallStaticObjectMethodA)(env, class(), id, args.as_ptr()); if invalid.is_null() || ((**env).v1_2.ExceptionCheck)(env) { fail(env, "jni", "a call into Kotlin threw"); } ((**env).v1_2.Throw)(env, invalid); } } /// What a native method returns once it threw, which Kotlin never reads: zeroed, as a /// JNI scalar or a null reference is. pub fn raised() -> R { // SAFETY: a native method returns only JNI scalars and references, all valid zeroed. unsafe { std::mem::zeroed() } } /// Run `f` calling into Kotlin on this thread, freeing the local references it makes, and /// abort if what it calls throws, unless `f` unwinds it with [`unwinds`]. pub fn upcall(what: &str, f: impl FnOnce(*mut JNIEnv) -> R) -> R { let env = env(); // SAFETY: `env` is this thread's. if unsafe { ((**env).v1_2.PushLocalFrame)(env, 8) } != JNI_OK { fail(env, what, "a call into Kotlin is out of memory"); } // Popped however `f` ends, unwinding included. UPCALLS.with(|n| n.set(n.get() + 1)); let frame = Frame(env); let result = f(env); threw(env, what); drop(frame); result } thread_local! { /// How many [`upcall`]s this thread is in. On a thread Rust attached, a native method is /// below a call into Kotlin only through an outer one, which called into Kotlin first. static UPCALLS: Cell = const { Cell::new(0) }; } /// The local frame an [`upcall`] pushed, popped once dropped. struct Frame(*mut JNIEnv); impl Drop for Frame { fn drop(&mut self) { UPCALLS.with(|n| n.set(n.get() - 1)); // SAFETY: the frame's thread pushed it, and no exception is pending: `threw` // aborts on one, and `unwinds` clears what it unwinds with. unsafe { ((**self.0).v1_2.PopLocalFrame)(self.0, std::ptr::null_mut()) }; } } /// Check the call into a closure or callback Kotlin implements: if Kotlin refused what it /// returned with `_Native.__Invalid`, as a value its Rust type cannot hold, or a call it /// made threw `_Native.__Unwound`, unwind the Rust frames between to the native method /// below, which throws `__Unwound` to the Kotlin call that reached the closure, as Rust's /// own closure panicking unwinds them. Anything else thrown aborts, as [`threw`] does. pub fn unwinds(env: *mut JNIEnv, what: &str) { if pending(env) { unwind(env, what); fail(env, what, "a call into Kotlin threw"); } } static UNWOUND: OnceLock = OnceLock::new(); /// Unwind with the `__Unwound` of the exception pending if it is the binding's `__Invalid` /// or `__Unwound`, aborting if no native method is below to throw it, as on a thread Rust /// attached that no outer [`upcall`] called into Kotlin on, or if a library built to abort /// on a panic cannot unwind. Any other stays pending. #[cold] fn unwind(env: *mut JNIEnv, what: &str) { // SAFETY: `env` is this thread's, and an exception is pending. unsafe { let thrown = ((**env).v1_2.ExceptionOccurred)(env); ((**env).v1_2.ExceptionClear)(env); let id = method(env, &UNWOUND, c"__unwound", c"(Ljava/lang/Throwable;)Ljava/lang/Throwable;"); let args = [jvalue { l: thrown }]; let unwound = ((**env).v1_2.CallStaticObjectMethodA)(env, class(), id, args.as_ptr()); if ((**env).v1_2.ExceptionCheck)(env) { fail(env, what, "a call into Kotlin threw"); } if unwound.is_null() { ((**env).v1_2.Throw)(env, thrown); return; } let below = !ATTACHED.with(|attached| attached.0.get()) || UPCALLS.with(Cell::get) > 1; if cfg!(not(panic = "unwind")) || !below { ((**env).v1_2.Throw)(env, unwound); fail(env, what, "a closure's value has no Rust type to be, and no Kotlin call to throw to"); } let global = ((**env).v1_2.NewGlobalRef)(env, unwound); if global.is_null() { fail(env, what, "a call into Kotlin is out of memory"); } std::panic::resume_unwind(Box::new(Unwound(global))) } } /// What a closure's failed check unwinds Rust with: a global reference to the /// `__Unwound` the native method below throws. struct Unwound(jobject); // SAFETY: a global reference is valid on every thread. unsafe impl Send for Unwound {} impl Drop for Unwound { fn drop(&mut self) { // SAFETY: made by `unwind`, and deleted once. A `catch_unwind` of Rust's own that // took it drops it as Rust drops any panic it caught. let env = env(); unsafe { ((**env).v1_2.DeleteGlobalRef)(env, self.0) }; } } /// Run a native method's glue `f`, throwing to Kotlin the exception a closure's failed /// check unwound with, as [`unwinds`] says. A Rust panic goes on, aborting at the native /// method's boundary. #[inline(always)] pub fn entry(env: *mut JNIEnv, f: impl FnOnce() -> R) -> R { match std::panic::catch_unwind(std::panic::AssertUnwindSafe(f)) { Ok(result) => result, Err(payload) => caught_unwind(env, payload), } } #[cold] fn caught_unwind(env: *mut JNIEnv, payload: Box) -> R { match payload.downcast::() { Ok(unwound) => { // SAFETY: `env` is this thread's, and nothing is pending: `unwind` cleared it. unsafe { ((**env).v1_2.Throw)(env, unwound.0) }; raised() } Err(panic) => std::panic::resume_unwind(panic), } } /// Abort if the call into Kotlin `f` just made threw: JNI allows no other call while an /// exception is pending, so a call whose result is read checks this first. pub fn threw(env: *mut JNIEnv, what: &str) { // SAFETY: `env` is this thread's. if unsafe { ((**env).v1_2.ExceptionCheck)(env) } { fail(env, what, "a call into Kotlin threw"); } } /// The static method `name` of the native class, whose type is `sig`, cached in `cache`. pub fn method(env: *mut JNIEnv, cache: &OnceLock, name: &CStr, sig: &CStr) -> jmethodID { *cache.get_or_init(|| { // SAFETY: `env` is this thread's, and the class is a global reference. let id = unsafe { ((**env).v1_2.GetStaticMethodID)(env, class(), name.as_ptr(), sig.as_ptr()) }; if id.is_null() { fail(env, "jni", "a Kotlin function the library calls is missing"); } id as usize }) as jmethodID } /// A `byte[]`'s bytes, copied, or none for null. pub fn bytes(env: *mut JNIEnv, array: jbyteArray) -> Option> { if array.is_null() { return None; } // SAFETY: `array` is a live `byte[]` the call was given. unsafe { let len = ((**env).v1_2.GetArrayLength)(env, array); let mut bytes = Vec::::with_capacity(len as usize); ((**env).v1_2.GetByteArrayRegion)(env, array, 0, len, bytes.as_mut_ptr().cast()); bytes.set_len(len as usize); Some(bytes) } } /// A number Kotlin holds in the primitive array of its width, which crosses JNI whole. pub trait Prim: Copy { /// Copy `len` of `array`'s numbers into `into`. /// /// # Safety /// `array` is a live array of this width holding `len`, and `into` has room for them. unsafe fn get(env: *mut JNIEnv, array: jarray, len: jsize, into: *mut Self); /// A new array of `len` numbers. /// /// # Safety /// `env` is this thread's. unsafe fn new(env: *mut JNIEnv, len: jsize) -> jarray; /// Copy `len` numbers from `from` into `array`. /// /// # Safety /// `array` is a live array of this width holding `len`, and `from` holds them. unsafe fn set(env: *mut JNIEnv, array: jarray, len: jsize, from: *const Self); } macro_rules! prim { ($($t:ty: $get:ident, $new:ident, $set:ident;)*) => {$( impl Prim for $t { unsafe fn get(env: *mut JNIEnv, array: jarray, len: jsize, into: *mut Self) { // SAFETY: the caller's contract. unsafe { ((**env).v1_2.$get)(env, array, 0, len, into.cast()) } } unsafe fn new(env: *mut JNIEnv, len: jsize) -> jarray { // SAFETY: the caller's contract. unsafe { ((**env).v1_2.$new)(env, len) } } unsafe fn set(env: *mut JNIEnv, array: jarray, len: jsize, from: *const Self) { // SAFETY: the caller's contract. unsafe { ((**env).v1_2.$set)(env, array, 0, len, from.cast()) } } } )*}; } prim! { i8: GetByteArrayRegion, NewByteArray, SetByteArrayRegion; u16: GetShortArrayRegion, NewShortArray, SetShortArrayRegion; i16: GetShortArrayRegion, NewShortArray, SetShortArrayRegion; u32: GetIntArrayRegion, NewIntArray, SetIntArrayRegion; i32: GetIntArrayRegion, NewIntArray, SetIntArrayRegion; u64: GetLongArrayRegion, NewLongArray, SetLongArrayRegion; i64: GetLongArrayRegion, NewLongArray, SetLongArrayRegion; f32: GetFloatArrayRegion, NewFloatArray, SetFloatArrayRegion; f64: GetDoubleArrayRegion, NewDoubleArray, SetDoubleArrayRegion; } /// A primitive array's numbers, copied in one call. pub fn block(env: *mut JNIEnv, array: jarray) -> Vec { if array.is_null() { rt::fail("jni", "a primitive array is null"); } // SAFETY: `array` is a live array of `T`'s width the call was given. unsafe { let len = ((**env).v1_2.GetArrayLength)(env, array); let mut items = Vec::::with_capacity(len as usize); T::get(env, array, len, items.as_mut_ptr()); items.set_len(len as usize); items } } /// `items` as the C array a call takes, which keeps them. pub fn list(items: &[T]) -> rt::List { rt::List { ptr: items.as_ptr(), len: items.len(), owner: std::ptr::null_mut(), } } /// A new primitive array of the numbers Rust returned, which it frees once copied. pub fn new_block(env: *mut JNIEnv, list: rt::List) -> jarray { // SAFETY: an array Rust returned, freed here once copied. unsafe { let items = list.items("jni"); let Ok(len) = jsize::try_from(items.len()) else { rt::fail("jni", "an array is too long for a Kotlin array") }; let array = T::new(env, len); if array.is_null() { fail(env, "jni", "a primitive array is out of memory"); } T::set(env, array, len, items.as_ptr()); list.free("jni", |_| {}); array } } /// A `String`'s UTF-8, encoded once, or none for null; or else, for one holding a lone /// surrogate, which UTF-8 has no form of, none at all, having thrown. pub fn text(env: *mut JNIEnv, text: jstring) -> Option>> { match text.is_null() { true => Some(None), false => utf8(env, text).map(Some), } } /// Bytes Rust takes, or none. pub fn buf(bytes: Option>) -> rt::Buf { bytes.map_or(rt::Buf::NONE, rt::Buf::vec) } /// A live `String`'s UTF-8, or none for one holding a lone surrogate, having thrown. JNI's /// own UTF-8 is modified, which differs for NUL and past the BMP, so the UTF-16 is read a /// chunk at a time and encoded here, checked as it is. fn utf8(env: *mut JNIEnv, text: jstring) -> Option> { const CHUNK: usize = 1024; // SAFETY: `text` is a live `String` the call was given. let len = unsafe { ((**env).v1_2.GetStringLength)(env, text) } as usize; let mut out = Vec::with_capacity(len); let mut chunk = [0u16; CHUNK]; let mut at = 0; while at < len { let n = (len - at).min(CHUNK); // SAFETY: `at + n` is within the string, and `chunk` holds `n`. unsafe { ((**env).v1_2.GetStringRegion)(env, text, at as jint, n as jint, chunk.as_mut_ptr()) }; let mut units = &chunk[..n]; // A pair split across chunks is read whole with the next. if at + n < len && (0xD800..0xDC00).contains(&units[n - 1]) { units = &units[..n - 1]; } at += units.len(); for c in char::decode_utf16(units.iter().copied()) { match c { Ok(c) if c.is_ascii() => out.push(c as u8), Ok(c) => out.extend_from_slice(c.encode_utf8(&mut [0; 4]).as_bytes()), Err(_) => { invalid(env, c"a String with a lone surrogate has no UTF-8, as Rust's text is"); return None; } } } } Some(out) } /// `len` bytes of a live `byte[]` from `start`, copied, failing loud past its end, which /// Kotlin's `Bytes` checks first. fn region(env: *mut JNIEnv, array: jbyteArray, start: jint, len: jint) -> Vec { let Ok(n) = usize::try_from(len) else { rt::fail("jni", "bytes passed have a negative length") }; let mut bytes = Vec::::with_capacity(n); // SAFETY: `array` is a live `byte[]`; JNI checks the range, throwing past its end. unsafe { ((**env).v1_2.GetByteArrayRegion)(env, array, start, len, bytes.as_mut_ptr().cast()); if ((**env).v1_2.ExceptionCheck)(env) { fail(env, "jni", "bytes passed are past their array's end"); } bytes.set_len(n); } bytes } /// The owner Kotlin passes for a `Bytes` over a direct `ByteBuffer`, which no buffer Rust /// lends has, as Kotlin's `_Native.__DIRECT`. const DIRECT_OWNER: jlong = -1; /// The memory of a live direct `ByteBuffer` from `start`, `len` long, failing loud past its /// capacity, which Kotlin checks first. fn direct_range(env: *mut JNIEnv, buffer: jobject, start: jint, len: jint) -> *mut u8 { // SAFETY: `buffer` is a live direct `ByteBuffer`, which `load` checked the JVM supports. let (base, capacity) = unsafe { ( ((**env).v1_4.GetDirectBufferAddress)(env, buffer).cast::(), ((**env).v1_4.GetDirectBufferCapacity)(env, buffer), ) }; match (usize::try_from(start), usize::try_from(len), usize::try_from(capacity)) { (Ok(start), Ok(len), Ok(capacity)) if start <= capacity && len <= capacity - start => match base.is_null() { // An empty buffer may have no memory at all. true if len == 0 => std::ptr::NonNull::dangling().as_ptr(), true => rt::fail("jni", "a direct buffer has no memory"), // SAFETY: within the buffer's memory, as just checked. false => unsafe { base.add(start) }, }, _ => rt::fail("jni", "bytes passed are past their direct buffer's end"), } } /// `len` bytes of a live direct `ByteBuffer` from `start`, copied once from its memory. fn direct(env: *mut JNIEnv, buffer: jobject, start: jint, len: jint) -> Vec { let from = direct_range(env, buffer, start, len); let n = len as usize; let mut bytes = Vec::::with_capacity(n); // SAFETY: `from` reaches `n` bytes, and `bytes` has room for them. Nothing writes them // meanwhile: `Bytes(ByteBuffer)` documents a write during the call as the caller's race. unsafe { std::ptr::copy_nonoverlapping(from, bytes.as_mut_ptr(), n); bytes.set_len(n); } bytes } /// Bytes Kotlin passes as a `Bytes` holds them, for Rust to take: none where `len` is -1, /// else those from `start` of what an `owner` Rust lent holds, shared without a copy, or of /// the direct `ByteBuffer` or the `byte[]` `held`, copied once. /// /// # Safety /// A non-zero `owner` came from [`hand`], and `held` keeps it from being freed. pub unsafe fn passed(env: *mut JNIEnv, held: jobject, owner: jlong, start: jint, len: jint) -> rt::Buf { if len == -1 { return rt::Buf::NONE; } if owner == DIRECT_OWNER { return rt::Buf::vec(direct(env, held, start, len)); } if owner != 0 { // SAFETY: the caller's contract. let bytes = unsafe { range(owner, start, len) }; let buf = rt::Buf { ptr: bytes.as_ptr(), len: bytes.len(), owner: owner as usize as _, }; // SAFETY: as above. return unsafe { buf.share("jni") }; } rt::Buf::vec(region(env, held, start, len)) } /// A new `byte[]` holding `bytes`. pub fn array(env: *mut JNIEnv, bytes: &[u8]) -> jbyteArray { // SAFETY: `bytes` holds its length in bytes. unsafe { raw_array(env, bytes.as_ptr(), bytes.len()) } } /// A new `byte[]` of the `len` bytes at `bytes`, which JNI copies as they are, so any may /// be uninitialized. /// /// # Safety /// `bytes` reaches `len` bytes. unsafe fn raw_array(env: *mut JNIEnv, bytes: *const u8, len: usize) -> jbyteArray { let Ok(len) = jsize::try_from(len) else { rt::fail("jni", "a buffer is too long for a byte[]") }; // SAFETY: `env` is this thread's, and `bytes` reaches `len` bytes. unsafe { let array = ((**env).v1_2.NewByteArray)(env, len); if array.is_null() { fail(env, "jni", "a byte[] is out of memory"); } ((**env).v1_2.SetByteArrayRegion)(env, array, 0, len, bytes.cast()); array } } /// The longest bytes Rust returns that cross copied, freed at once: a lent buffer costs a /// cleaner registration, and a call per read, which copying up to about this many bytes /// undercuts. const COPIED: usize = 1024; /// The most bytes lent to Kotlin at once, freed or not. The GC sees none of them, so a /// program making little garbage of its own would never collect the `Bytes` holding them; /// past this, bytes cross copied into Kotlin's heap, whose garbage the GC does see. const LENT_MAX: usize = 64 << 20; /// The bytes lent to Kotlin and not yet freed. static LENT_BYTES: AtomicUsize = AtomicUsize::new(0); /// Whether `len` bytes cross lent rather than copied: longer than [`COPIED`], and within /// [`LENT_MAX`], which they then count against until freed. A call racing another past /// the limit may copy where it could have lent, never the reverse. fn lends(len: usize) -> bool { if len <= COPIED { return false; } if LENT_BYTES.fetch_add(len, Ordering::Relaxed) + len <= LENT_MAX { return true; } LENT_BYTES.fetch_sub(len, Ordering::Relaxed); false } /// A buffer Rust returned or lent, as Kotlin's `_Native.owned` takes it: null for none, a /// `byte[]` copy, freeing the buffer, or where it [`lends`] a `long[]` holding the owner it /// lends them through and their length. /// /// # Safety /// `buf` is a buffer Rust returned or lent, freed by nothing else. pub unsafe fn hand(env: *mut JNIEnv, buf: rt::Buf) -> jobject { if buf.is_none() { return std::ptr::null_mut(); } if !lends(buf.len) { // SAFETY: the caller's contract. return unsafe { let array = array(env, buf.bytes("jni")); buf.free(); array }; } let len = lent_len(&buf); // SAFETY: the caller's contract. let lent = [unsafe { self::owner(buf) }, len.into()]; // SAFETY: `env` is this thread's. unsafe { let array = ((**env).v1_2.NewLongArray)(env, 2); if array.is_null() { fail(env, "jni", "a long[] is out of memory"); } ((**env).v1_2.SetLongArrayRegion)(env, array, 0, 2, lent.as_ptr()); array } } /// The length of a buffer handed to Kotlin, whose `Bytes` counts in an `Int`. fn lent_len(buf: &rt::Buf) -> i32 { match i32::try_from(buf.len) { Ok(len) => len, Err(_) => rt::fail("jni", "a buffer is too long for Bytes"), } } /// 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") })), false => buf, }; buf.owner as usize as jlong } /// The bytes `owner` holds from `start`, `len` long, failing loud past their end, which /// Kotlin checks first. /// /// # Safety /// `owner` came from [`hand`], and is not yet freed. unsafe fn range<'a>(owner: jlong, start: jint, len: jint) -> &'a [u8] { // SAFETY: the caller's contract; the owner holds the bytes until freed. let bytes = unsafe { let buf = rt::Buf::of_owner(owner as usize as _); std::slice::from_raw_parts(buf.ptr, buf.len) }; match (usize::try_from(start), usize::try_from(len)) { (Ok(start), Ok(len)) if start <= bytes.len() && len <= bytes.len() - start => &bytes[start..start + len], _ => rt::fail("jni", "a read is past a lent buffer's end"), } } /// The byte at `index` of those `owner` holds. /// /// # Safety /// As [`range`]. pub unsafe fn byte_at(owner: jlong, index: jint) -> jbyte { // SAFETY: the caller's contract. unsafe { range(owner, index, 1)[0] as jbyte } } /// Copy the bytes `owner` holds from `start`, `len` long, into `array` at `at`. /// /// # Safety /// As [`range`], and `array` is a live `byte[]`. pub unsafe fn copy(env: *mut JNIEnv, owner: jlong, start: jint, len: jint, array: jbyteArray, at: jint) { // SAFETY: the caller's contract; JNI throws if `array` is too short. unsafe { let bytes = range(owner, start, len); ((**env).v1_2.SetByteArrayRegion)(env, array, at, len, bytes.as_ptr().cast()); } } /// Copy the bytes `owner` holds from `start`, `len` long, into the memory of `buffer`, a /// direct `ByteBuffer`, at `at`. /// /// # Safety /// As [`range`], and `buffer` is a live direct `ByteBuffer`. pub unsafe fn copy_direct(env: *mut JNIEnv, owner: jlong, start: jint, len: jint, buffer: jobject, at: jint) { let to = direct_range(env, buffer, at, len); // SAFETY: the caller's contract, and `to` reaches `len` bytes; Rust's never overlap Java's, // and nothing touches them meanwhile, as `Bytes.copyInto(ByteBuffer)` documents. unsafe { let bytes = range(owner, start, len); std::ptr::copy_nonoverlapping(bytes.as_ptr(), to, bytes.len()); } } /// Free the bytes `owner` holds. /// /// # Safety /// `owner` came from [`hand`], and is freed once. pub unsafe fn free_bytes(owner: jlong) { // SAFETY: the caller's contract. let buf = unsafe { rt::Buf::of_owner(owner as usize as _) }; let len = buf.len; // SAFETY: the caller's contract. unsafe { buf.free() }; LENT_BYTES.fetch_sub(len, Ordering::Relaxed); } /// A buffer Rust returned as a `byte[]`, or null for none, freeing it. /// /// # Safety /// `buf` is a buffer Rust returned, freed by nothing else. pub unsafe fn owned(env: *mut JNIEnv, buf: rt::Buf) -> jbyteArray { if buf.is_none() { return std::ptr::null_mut(); } // SAFETY: the caller's contract. unsafe { let array = array(env, buf.bytes("jni")); buf.free(); array } } /// A buffer Rust lent for a call as a `byte[]`, or null for none. /// /// # Safety /// `buf` is a buffer Rust lent for the call. pub unsafe fn lent(env: *mut JNIEnv, buf: rt::Buf) -> jbyteArray { match buf.is_none() { true => std::ptr::null_mut(), // SAFETY: the caller's contract. false => array(env, unsafe { buf.bytes("jni") }), } } /// Set the first of Kotlin's `long[]` `slots` to `values`: a returned record's scalars, /// which cross with no `byte[]` to allocate and decode. Slots shorter than `values` throw. pub fn slots(env: *mut JNIEnv, slots: jlongArray, values: &[i64]) { // SAFETY: `env` is this thread's, `slots` a live `long[]` the call was given, and // `values` holds `values.len()` longs, which a record's few scalars fit a `jsize`. unsafe { ((**env).v1_2.SetLongArrayRegion)(env, slots, 0, values.len() as jsize, values.as_ptr()) } } /// A global reference to a Kotlin value, which Rust may hold on any thread. pub fn global(env: *mut JNIEnv, value: jobject) -> *mut c_void { if value.is_null() { rt::fail("jni", "a Kotlin value is null"); } // SAFETY: `env` is this thread's, and `value` a live reference. unsafe { ((**env).v1_2.NewGlobalRef)(env, value).cast() } } /// Delete a global reference [`global`] made, from any thread. /// /// # Safety /// `data` is a global reference, deleted once. pub unsafe extern "C" fn free_global(data: *mut c_void) { let env = env(); // SAFETY: the caller's contract. unsafe { ((**env).v1_2.DeleteGlobalRef)(env, data.cast()) }; } static FREE: OnceLock = OnceLock::new(); /// Let go of a Kotlin implementation of a trait, from any thread: closed first if it is /// `AutoCloseable`. /// /// # Safety /// `data` is a global reference, deleted once. pub unsafe extern "C" fn free_callback(data: *mut c_void) { upcall("free", |env| { let id = method(env, &FREE, c"__free", c"(Ljava/lang/Object;)V"); let args = [jvalue { l: data.cast() }]; // SAFETY: `__free` takes the implementation. unsafe { ((**env).v1_2.CallStaticVoidMethodA)(env, class(), id, args.as_ptr()) }; }); // SAFETY: the caller's contract. unsafe { free_global(data) }; } /// A global reference for the length of a call. pub struct Global(pub *mut c_void); impl Global { pub fn new(env: *mut JNIEnv, value: jobject) -> Self { Self(global(env, value)) } } impl Drop for Global { fn drop(&mut self) { // SAFETY: made by `new`, and dropped once. unsafe { free_global(self.0) }; } } /// A Kotlin `Waker`, counted: Rust holds one reference per waker it was given, and Kotlin /// one while it polls a future with it. pub struct Node { waker: *mut c_void, refs: AtomicUsize, } /// A node holding one reference, for a `Waker`. pub fn node(env: *mut JNIEnv, waker: jobject) -> *mut Node { Box::into_raw(Box::new(Node { waker: global(env, waker), refs: AtomicUsize::new(1), })) } /// Drop a reference to `node`, freeing it with the last. /// /// # Safety /// The caller holds a reference to `node`. pub unsafe extern "C" fn unref(node: *mut c_void) { let node = node.cast::(); // SAFETY: the caller's contract. if unsafe { &*node }.refs.fetch_sub(1, Ordering::AcqRel) == 1 { // SAFETY: that was the last reference. let node = unsafe { Box::from_raw(node) }; // SAFETY: the node made the global reference. unsafe { free_global(node.waker) }; } } static WAKE: OnceLock = OnceLock::new(); unsafe extern "C" fn wake(node: *mut c_void) { // SAFETY: Rust holds a reference to the node while it may wake it. let waker = unsafe { &*node.cast::() }.waker; upcall("wake", |env| { let id = method(env, &WAKE, c"__wake", c"(Ljava/lang/Object;)V"); let args = [jvalue { l: waker.cast() }]; // SAFETY: `wake` takes the waker. unsafe { ((**env).v1_2.CallStaticVoidMethodA)(env, class(), id, args.as_ptr()) }; }); } /// `node` as a waker that borrows its reference: a poll given it again reuses it rather /// than dropping it. pub fn lend(node: *mut Node) -> rt::Waker { rt::Waker { wake: Some(wake), drop: Some(unref), data: node.cast(), } } /// `node` as a waker holding a new reference, which Rust drops. /// /// # Safety /// The caller holds a reference to `node`. pub unsafe fn give(node: *mut Node) -> rt::Waker { // SAFETY: the caller's contract. unsafe { &*node }.refs.fetch_add(1, Ordering::Relaxed); lend(node) } /// Poll a future with a waker, writing its result into the writer if it finished, or a /// failed check's status into the last, for a future that is not `Send`. pub type Poll = unsafe fn(*mut c_void, rt::Waker, &mut Writer, &mut i32) -> bool; /// Poll the future just made, and free it if it finished: the call and its first poll are /// one crossing. Its writer holds a bool, true when finished, then the result, or else the /// future and the waker node made for `signal`, which Kotlin polls and frees. /// /// # Safety /// `future` is a live future that `poll` and `free` take, and `signal` a Kotlin `Waker`. /// None once a poll's check failed, which throws as the native method returns. pub unsafe fn start( env: *mut JNIEnv, future: *mut c_void, signal: jobject, poll: Poll, free: unsafe fn(*mut c_void), what: &str, ) -> Option { let mut w = Writer::default(); w.put(true); // Most futures are ready at once, so the first poll takes no waker: a node costs a // global reference, and two crossings to free it. let none = rt::Waker { wake: None, drop: None, data: std::ptr::null_mut(), }; let mut status = 0; // A poll that unwinds frees what Kotlin has no handle yet to free. let mut started = Started { future, free, node: std::ptr::null_mut() }; // SAFETY: the caller's contract. let ready = unsafe { poll(future, none, &mut w, &mut status) }; if ready || status != 0 { std::mem::forget(started); // SAFETY: as above, and it finished, or is never polled again. unsafe { free(future) }; return match status { 0 => Some(w), _ => { refuse::<()>(env, status, what); None } }; } // Pending, so polled again with the waker it parks on, which replaces the first. let node = node(env, signal); started.node = node; // SAFETY: as above, and `node` holds a reference for this. let ready = unsafe { poll(future, give(node), &mut w, &mut status) }; std::mem::forget(started); if ready { // SAFETY: as above. unsafe { free(future); unref(node.cast()); } return Some(w); } let mut w = Writer::default(); w.put(false); w.put(future); w.put(node.cast::()); Some(w) } /// A future [`start`] polls, and the waker node made for it, if any, freed once dropped. struct Started { future: *mut c_void, free: unsafe fn(*mut c_void), node: *mut Node, } impl Drop for Started { fn drop(&mut self) { // SAFETY: `start`'s contract; Kotlin got neither, so this is their only free. unsafe { (self.free)(self.future); if !self.node.is_null() { unref(self.node.cast()); } } } } /// Poll `future` again with `node`, whose reference Rust holds from the first poll that /// pended: its result, or null while pending. /// /// # Safety /// `future` is a live future that `poll` takes, and Rust holds a reference to `node`. /// A failed check throws as the native method returns, which ignores its null. pub unsafe fn poll(env: *mut JNIEnv, future: *mut c_void, node: *mut Node, poll: Poll, what: &str) -> Option { let mut w = Writer::default(); let mut status = 0; // SAFETY: the caller's contract. match unsafe { poll(future, lend(node), &mut w, &mut status) } { true => Some(w), false if status != 0 => { refuse::<()>(env, status, what); None } false => None, } } static POLL: OnceLock = OnceLock::new(); /// A Kotlin `Pollable` as the future Rust polls, which Rust closes once it drops it. pub fn future(env: *mut JNIEnv, pollable: jobject) -> rt::ForeignFuture { rt::ForeignFuture { poll: Some(poll_future), free: Some(free_callback), data: global(env, pollable), } } /// Poll a Kotlin `Pollable`, from any thread, handing it Rust's waker as [`returned`] /// boxes it. unsafe extern "C" fn poll_future(data: *mut c_void, waker: rt::Waker) -> bool { let waker = returned(waker); upcall("poll", |env| { let id = method(env, &POLL, c"__poll", c"(Ljava/lang/Object;J)Z"); let args = [jvalue { l: data.cast() }, jvalue { j: waker }]; // SAFETY: `__poll` takes the `Pollable` and the waker's pointer. unsafe { ((**env).v1_2.CallStaticBooleanMethodA)(env, class(), id, args.as_ptr()) } }) } static READ: OnceLock = OnceLock::new(); static SEEK: OnceLock = OnceLock::new(); static IO_ERROR: OnceLock = OnceLock::new(); static ERROR: OnceLock = OnceLock::new(); /// A Kotlin `SeekableByteChannel`, held by the global reference `channel`, as the reader /// Rust reads for the call. pub fn reader(channel: *mut c_void) -> rt::ForeignReader { rt::ForeignReader { read: Some(read_channel), seek: Some(seek_channel), data: channel, } } /// Read a Kotlin channel into `buf`, from any thread: as many bytes as one `read` gives, /// copied out of the `byte[]` Kotlin fills, so Kotlin never sees Rust's memory. unsafe extern "C" fn read_channel(data: *mut c_void, buf: *mut u8, len: usize, n: *mut usize, err: *mut rt::Buf) -> bool { upcall("SeekableByteChannel.read", |env| { let id = method(env, &READ, c"__read", c"(Ljava/lang/Object;I)[B"); let asked = len.min(jint::MAX as usize); let args = [jvalue { l: data.cast() }, jvalue { i: asked as jint }]; // SAFETY: `__read` takes the channel and how many bytes to read. let array = unsafe { ((**env).v1_2.CallStaticObjectMethodA)(env, class(), id, args.as_ptr()) }; if let Some(error) = caught(env, "SeekableByteChannel.read", &IO_ERROR, c"__io_error") { // SAFETY: C's contract: `err` is writable. unsafe { err.write(rt::Buf::vec(error)) }; return false; } // SAFETY: `__read` returned a `byte[]` of at most `asked` bytes, which `buf` holds. unsafe { let read = ((**env).v1_2.GetArrayLength)(env, array).clamp(0, asked as jint); ((**env).v1_2.GetByteArrayRegion)(env, array, 0, read, buf.cast()); n.write(read as usize); } true }) } /// Seek a Kotlin channel, from any thread. unsafe extern "C" fn seek_channel(data: *mut c_void, whence: std::ffi::c_int, offset: i64, position: *mut u64, err: *mut rt::Buf) -> bool { upcall("SeekableByteChannel.position", |env| { let id = method(env, &SEEK, c"__seek", c"(Ljava/lang/Object;IJ)J"); let args = [jvalue { l: data.cast() }, jvalue { i: whence }, jvalue { j: offset }]; // SAFETY: `__seek` takes the channel, where to seek from, and how far. let at = unsafe { ((**env).v1_2.CallStaticLongMethodA)(env, class(), id, args.as_ptr()) }; if let Some(error) = caught(env, "SeekableByteChannel.position", &IO_ERROR, c"__io_error") { // SAFETY: C's contract: `err` is writable. unsafe { err.write(rt::Buf::vec(error)) }; return false; } // SAFETY: C's contract: `position` is writable. Its bits, unsigned, as `__seek` returns // a position past `Long.MAX_VALUE`. unsafe { position.write(at.cast_unsigned()) }; true }) } /// The error of the exception a closure threw, cleared, if it is the binding's own /// exception of a `String`, as a closure returning a `Result` fails. A value its Rust type /// cannot hold unwinds, as [`unwinds`] says. pub fn thrown(env: *mut JNIEnv, what: &str) -> Option> { if pending(env) { unwind(env, what); } caught(env, what, &ERROR, c"__error") } /// The error of the exception pending, cleared, if the Kotlin function `name` takes it /// as one Rust returns; none if nothing threw. Any other aborts, as [`upcall`] does. fn caught(env: *mut JNIEnv, what: &str, cache: &OnceLock, name: &CStr) -> Option> { // SAFETY: `env` is this thread's, and `thrown` a live reference. unsafe { let thrown = ((**env).v1_2.ExceptionOccurred)(env); if thrown.is_null() { return None; } ((**env).v1_2.ExceptionClear)(env); let id = method(env, cache, name, c"(Ljava/lang/Throwable;)[B"); let args = [jvalue { l: thrown }]; let error = ((**env).v1_2.CallStaticObjectMethodA)(env, class(), id, args.as_ptr()); if error.is_null() && !((**env).v1_2.ExceptionCheck)(env) { ((**env).v1_2.Throw)(env, thrown); } if ((**env).v1_2.ExceptionCheck)(env) { fail(env, what, "a call into Kotlin threw"); } bytes(env, error) } } static FAILED: OnceLock = OnceLock::new(); /// Raise the error a function returned, encoded in `w`, as the `_Native.__Failed` Kotlin turns /// into its exception: a call's success path then returns its value with no `byte[]`. pub fn raise(env: *mut JNIEnv, w: Writer) { let id = method(env, &FAILED, c"__failed", c"([B)Ljava/lang/Throwable;"); let args = [jvalue { l: w.array(env) }]; // SAFETY: `env` is this thread's, and `__failed` takes the error's bytes. unsafe { let failed = ((**env).v1_2.CallStaticObjectMethodA)(env, class(), id, args.as_ptr()); if failed.is_null() || ((**env).v1_2.ExceptionCheck)(env) { fail(env, "jni", "a call into Kotlin threw"); } ((**env).v1_2.Throw)(env, failed); } } /// A Kotlin `Waker` passed by value: Rust holds its only reference. pub fn waker(env: *mut JNIEnv, waker: jobject) -> rt::Waker { lend(node(env, waker)) } /// A waker a function returned, boxed for Kotlin to hold as a `long`. pub fn returned(waker: rt::Waker) -> jlong { Box::into_raw(Box::new(waker)) as usize as jlong } /// Wake a waker [`returned`] boxed. /// /// # Safety /// `raw` is one [`returned`] made, not yet dropped. pub unsafe fn wake_returned(raw: jlong) { // SAFETY: the caller's contract. unsafe { (*(raw as usize as *const rt::Waker)).wake() }; } /// Drop a waker [`returned`] boxed. /// /// # Safety /// `raw` is one [`returned`] made, dropped only here. pub unsafe fn drop_returned(raw: jlong) { // SAFETY: the caller's contract. unsafe { Box::from_raw(raw as usize as *mut rt::Waker).release() }; } /// Encoded values, read in the order they were written, with the arrays read, which the /// arrays' views point into until the reader drops. pub struct Reader<'a> { bytes: &'a [u8], arrays: Vec>, /// The call's thread, and the arrays the encoding names by place. env: *mut JNIEnv, refs: jobjectArray, /// The UTF-8 of each text the encoding names, in order, and how many it has read. texts: Vec>, read: usize, /// Whether the value read is one Rust takes, so Rust's own bytes in it, outside an /// array, cross as a second owner of them rather than a view. take: bool, } impl<'a> Reader<'a> { /// A reader of a value Rust only reads, as through a pointer, whose encoding names /// the objects of `refs` by place, with the place of each text after it; or none, /// having thrown, if a text holds a lone surrogate. Each text is encoded before any of /// the value is read, so nothing read needs freeing when one throws. pub fn new(env: *mut JNIEnv, bytes: &'a [u8], refs: jobjectArray) -> Option { let mut r = Self::plain(bytes); if refs.is_null() { return Some(r); } (r.env, r.refs) = (env, refs); let count = r.trailer(1)[0]; let places = r.trailer(count as usize); r.texts = Vec::with_capacity(places.len()); for place in places { let text = r.object(place, |env, text| utf8(env, text))?; r.texts.push(text); } Some(r) } /// A reader of a value passed by value, which Rust takes. pub fn taking(env: *mut JNIEnv, bytes: &'a [u8], refs: jobjectArray) -> Option { Self::new(env, bytes, refs).map(|r| Self { take: true, ..r }) } /// A reader of a value that names no object, as a callback's return. pub fn plain(bytes: &'a [u8]) -> Self { Self { bytes, arrays: Vec::new(), env: std::ptr::null_mut(), refs: std::ptr::null_mut(), texts: Vec::new(), read: 0, take: false, } } /// The last `n` `i32`s of the encoding, taken off its end. fn trailer(&mut self, n: usize) -> Vec { let Some(at) = self.bytes.len().checked_sub(4 * n) else { rt::fail("jni", "an encoded value is truncated"); }; let (head, tail) = self.bytes.split_at(at); self.bytes = head; tail.chunks_exact(4) .map(|b| i32::from_le_bytes(b.try_into().expect("4 bytes"))) .collect() } /// What `make` makes of the object at `at` of `refs`. fn object(&mut self, at: i32, make: impl FnOnce(*mut JNIEnv, jobject) -> T) -> T { if self.refs.is_null() { rt::fail("jni", "an encoded value names an object, but none were passed"); } let env = self.env; // SAFETY: `refs` is the live `Object[]` the call was given; JNI throws past its end. let object = unsafe { ((**env).v1_2.GetObjectArrayElement)(env, self.refs, at) }; // SAFETY: as above. if object.is_null() || unsafe { ((**env).v1_2.ExceptionCheck)(env) } { fail(env, "jni", "an encoded value names no object"); } let made = make(env, object); // SAFETY: a local reference made here. unsafe { ((**env).v1_2.DeleteLocalRef)(env, object) }; made } /// The next text the encoding names, as [`Self::kept`] keeps it. fn text(&mut self) -> rt::Buf { let Some(text) = self.texts.get_mut(self.read) else { rt::fail("jni", "an encoded value names more text than it has"); }; self.read += 1; match self.take { true => rt::Buf::vec(std::mem::take(text)), // The vector's heap block, which the view reads, stays put until the reader drops. false => rt::Buf::view(text), } } /// Bytes made once by `make` from the object at `at` of `refs`: taken where the reader /// takes, else kept until it drops and read in place. fn referred(&mut self, at: i32, make: impl FnOnce(*mut JNIEnv, jobject) -> Vec) -> rt::Buf { let bytes = self.object(at, make); if self.take { return rt::Buf::vec(bytes); } let view = rt::Buf::view(&bytes); // The vector's heap block, which the view reads, stays put as the box moves. self.arrays.push(Box::new(bytes)); view } fn take(&mut self, n: usize) -> &'a [u8] { if self.bytes.len() < n { rt::fail("jni", "an encoded value is truncated"); } let (head, rest) = self.bytes.split_at(n); self.bytes = rest; head } pub fn get(&mut self) -> T { T::read(self) } } thread_local! { /// The native codec buffer, kept between calls and lent only while a return factory runs. static SCRATCH: Cell>> = const { Cell::new(Vec::new()) }; } /// Values encoded into a `byte[]` for Kotlin. It holds `MaybeUninit` bytes, the units an /// opaque value's C struct is made of, and hands JNI them by pointer. pub struct Writer(Vec>); impl Default for Writer { fn default() -> Self { Self(SCRATCH.try_with(Cell::take).unwrap_or_default()) } } impl Drop for Writer { fn drop(&mut self) { let mut buf = std::mem::take(&mut self.0); // A large one is let go, so no thread keeps the biggest value it ever returned. if buf.capacity() <= 4096 { buf.clear(); let _ = SCRATCH.try_with(|scratch| scratch.set(buf)); } } } impl Writer { pub fn put(&mut self, value: T) { value.write(self); } pub fn array(self, env: *mut JNIEnv) -> jbyteArray { // SAFETY: the vector holds its length in bytes, which JNI copies as they are. unsafe { raw_array(env, self.0.as_ptr().cast(), self.0.len()) } } fn extend(&mut self, bytes: &[u8]) { // SAFETY: a `u8` is a `MaybeUninit`. self.0.extend_from_slice(unsafe { &*(std::ptr::from_ref(bytes) as *const [MaybeUninit]) }); } /// Construct a Kotlin value while this writer's native buffer is alive. The generated /// factory reads it completely and retains neither the buffer nor its reader. pub fn value(self, env: *mut JNIEnv, cache: &OnceLock, name: &CStr, back: jobject) -> jobject { let id = method(env, cache, name, c"(Ljava/nio/ByteBuffer;[Ljava/lang/Object;)Ljava/lang/Object;"); let len = i32::try_from(self.0.len()).unwrap_or_else(|_| rt::fail("jni", "a value is too large for a ByteBuffer")); // SAFETY: this writer owns the allocation through the synchronous factory call. // Even an empty Vec has a non-null aligned pointer. Kotlin cannot retain the view. unsafe { let buffer = ((**env).v1_4.NewDirectByteBuffer)(env, self.0.as_ptr() as *mut c_void, len as jlong); if buffer.is_null() { fail(env, "jni", "cannot make a return buffer"); } let args = [jvalue { l: buffer }, jvalue { l: back }]; let result = ((**env).v1_2.CallStaticObjectMethodA)(env, class(), id, args.as_ptr()); // A declared Rust error is thrown by the factory, after applying writebacks. // Leave it pending for the JVM, including a null success such as Option::None. ((**env).v1_2.DeleteLocalRef)(env, buffer); result } } } /// An opaque value's C struct from the `W` `long`s Kotlin holds it in: its bytes, in the /// words' order, as [`to_words`] put them. pub fn from_words(words: [jlong; W]) -> T { const { assert!(size_of::() <= W * size_of::()) }; let mut value = std::mem::MaybeUninit::::zeroed(); // SAFETY: `T` is a struct of `MaybeUninit` units, any bytes of which are one. unsafe { std::ptr::copy_nonoverlapping(words.as_ptr().cast::(), value.as_mut_ptr().cast::(), size_of::()); value.assume_init() } } /// The `W` `long`s Kotlin holds an opaque value's C struct in: its bytes, then zeros. /// Kotlin compares a value class of one by it. pub fn to_words(value: T) -> [jlong; W] { const { assert!(size_of::() <= W * size_of::()) }; let mut words = [0; W]; // SAFETY: an opaque value's C struct initializes every byte, as the glue makes it. unsafe { std::ptr::copy_nonoverlapping((&raw const value).cast::(), words.as_mut_ptr().cast::(), size_of::()) }; words } /// An opaque value's C struct as it crosses encoded: the `W` words Kotlin holds it in, /// whose little-endian bytes are its own on a little-endian target. pub fn read_words(r: &mut Reader<'_>) -> T { const { assert!(size_of::() <= W * size_of::() && cfg!(target_endian = "little")) }; let bytes = r.take(W * size_of::()); let mut value = std::mem::MaybeUninit::::zeroed(); // SAFETY: `T` is a struct of `MaybeUninit` units, any bytes of which are one. unsafe { std::ptr::copy_nonoverlapping(bytes.as_ptr(), value.as_mut_ptr().cast::(), size_of::()); value.assume_init() } } /// Encode an opaque value's C struct as the `W` words Kotlin holds it in: its bytes, then /// zeros. pub fn write_words(w: &mut Writer, value: T) { const { assert!(size_of::() <= W * size_of::() && cfg!(target_endian = "little")) }; let n = W * size_of::(); w.0.reserve(n); let start = w.0.len(); // SAFETY: the vector has room for `n` more bytes, each written before its length grows. unsafe { let at = w.0.as_mut_ptr().add(start).cast::(); std::ptr::write_bytes(at, 0, n); std::ptr::copy_nonoverlapping((&raw const value).cast::(), at, size_of::()); w.0.set_len(start + n); } } /// A C value as it crosses encoded: Kotlin writes one Rust reads, and Rust writes one it /// owns, freeing what it holds once copied. pub trait Wire: Sized { fn read(r: &mut Reader<'_>) -> Self; fn write(self, w: &mut Writer); } macro_rules! scalar { ($($t:ty),*) => {$( impl Wire for $t { fn read(r: &mut Reader<'_>) -> Self { Self::from_le_bytes(r.take(size_of::()).try_into().expect("taken")) } fn write(self, w: &mut Writer) { w.extend(&self.to_le_bytes()); } } )*}; } scalar!(u8, u16, u32, u64, i8, i16, i32, i64, f32, f64); impl Wire for [u8; N] { fn read(r: &mut Reader<'_>) -> Self { r.take(N).try_into().expect("taken") } fn write(self, w: &mut Writer) { w.extend(&self); } } impl Wire for bool { fn read(r: &mut Reader<'_>) -> Self { r.get::() != 0 } fn write(self, w: &mut Writer) { w.put(u8::from(self)); } } /// What crosses as 64 bits, at the target's width: on a 32-bit target, a value past it /// has no `usize` or `isize` to be, which Kotlin's `__usize` and `__isize` throw on before /// it crosses, so this never fails for a value Kotlin passes. pub fn narrow, W>(wide: W) -> T { match T::try_from(wide) { Ok(v) => v, Err(_) => rt::fail("jni", "a value is too wide for this target's usize or isize"), } } impl Wire for usize { fn read(r: &mut Reader<'_>) -> Self { narrow(r.get::()) } fn write(self, w: &mut Writer) { w.put(self as u64); } } impl Wire for isize { fn read(r: &mut Reader<'_>) -> Self { narrow(r.get::()) } fn write(self, w: &mut Writer) { w.put(self as i64); } } impl Wire for *const c_void { fn read(r: &mut Reader<'_>) -> Self { narrow::(r.get::()) as Self } fn write(self, w: &mut Writer) { w.put(self as usize as u64); } } impl Wire for *mut c_void { fn read(r: &mut Reader<'_>) -> Self { narrow::(r.get::()) as Self } fn write(self, w: &mut Writer) { w.put(self as usize as u64); } } /// A returned waker, as [`returned`] boxes it. impl Wire for rt::Waker { fn read(r: &mut Reader<'_>) -> Self { // SAFETY: `write` boxed it, and Kotlin read it back once. *unsafe { Box::from_raw(narrow::(r.get::()) as *mut rt::Waker) } } fn write(self, w: &mut Writer) { w.put(returned(self)); } } impl Wire for rt::Buf { /// A view of the encoded bytes, or after [`LENT`] of those Rust lent Kotlin, in place, /// either of which outlives the call. fn read(r: &mut Reader<'_>) -> Self { match r.get::() { LENT => { let owner = r.get::(); let (start, len) = (r.get::(), r.get::()); // SAFETY: an owner Kotlin keeps from being freed until the call returns. let bytes = unsafe { range(owner, start, len) }; let view = rt::Buf::view(bytes); match r.take { false => view, // SAFETY: as above. true => unsafe { rt::Buf { owner: owner as usize as _, ..view } .share("jni") }, } } KOTLIN => { let at = r.get::(); let (start, len) = (r.get::(), r.get::()); r.referred(at, |env, array| region(env, array, start, len)) } DIRECT => { let at = r.get::(); let (start, len) = (r.get::(), r.get::()); r.referred(at, |env, buffer| direct(env, buffer, start, len)) } TEXT => r.text(), len => match usize::try_from(len) { Ok(len) => rt::Buf::view(r.take(len)), Err(_) => rt::Buf::NONE, }, } } fn write(self, w: &mut Writer) { if self.is_none() { w.put(-1i32); return; } // SAFETY: a buffer Rust returned, freed here once copied. let bytes = unsafe { self.bytes("jni") }; let Ok(len) = i32::try_from(bytes.len()) else { rt::fail("jni", "a buffer is too long for a byte[]") }; w.put(len); w.extend(bytes); // SAFETY: as above. unsafe { self.free() }; } } /// 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; /// What precedes the place in a call's objects of Kotlin's `byte[]`, then where its bytes /// start and how many, where an encoded buffer's length would. const KOTLIN: i32 = -3; /// What precedes the place in a call's objects of a direct `ByteBuffer`, then where its bytes /// start and how many, where an encoded buffer's length would. const DIRECT: i32 = -5; /// What marks the next of a call's texts, which its objects hold, where an encoded buffer's /// length would. const TEXT: i32 = -4; impl Wire for Owned { fn read(_: &mut Reader<'_>) -> Self { rt::fail("jni", "Kotlin passes bytes, never their owner") } // None as -1, bytes it [`lends`] as [`LENT`], their owner, and their length, and others // as their length and a copy. fn write(self, w: &mut Writer) { let buf = self.0; if buf.is_none() { w.put(-1i32); return; } let len = lent_len(&buf); if lends(buf.len) { w.put(LENT); // SAFETY: a buffer Rust returned or lent, handed over here. w.put(unsafe { owner(buf) }); w.put(len); } else { w.put(len); // SAFETY: a buffer Rust returned or lent, freed here once copied. unsafe { w.extend(buf.bytes("jni")); buf.free(); } } } } impl Wire for Owned> where Owned: Wire, { fn read(_: &mut Reader<'_>) -> Self { rt::fail("jni", "Kotlin passes bytes, never their owner") } fn write(self, w: &mut Writer) { let list = self.0; if list.is_none() { w.put(-1i32); return; } let Ok(len) = i32::try_from(list.len) else { rt::fail("jni", "an array is too long for a List") }; w.put(len); // SAFETY: an array Rust returned, whose elements move into the writer, so it is // freed without them. unsafe { list.items("jni").iter().for_each(|&item| w.put(Owned(item))); rt::List { len: 0, ..list }.free("jni", |_| {}); } } } impl Wire for rt::U128 { fn read(r: &mut Reader<'_>) -> Self { Self { lo: r.get(), hi: r.get() } } fn write(self, w: &mut Writer) { w.put(self.lo); w.put(self.hi); } } impl Wire for rt::Duration { fn read(r: &mut Reader<'_>) -> Self { Self { secs: r.get(), nanos: r.get(), } } fn write(self, w: &mut Writer) { w.put(self.secs); w.put(self.nanos); } } impl Wire for rt::Ipv4Addr { fn read(r: &mut Reader<'_>) -> Self { Self { octets: std::array::from_fn(|_| r.get()), } } fn write(self, w: &mut Writer) { self.octets.into_iter().for_each(|b| w.put(b)); } } impl Wire for rt::Ipv6Addr { fn read(r: &mut Reader<'_>) -> Self { Self { octets: std::array::from_fn(|_| r.get()), } } fn write(self, w: &mut Writer) { self.octets.into_iter().for_each(|b| w.put(b)); } } /// Whether it is IPv6, then the address of its family. impl Wire for rt::IpAddr { fn read(r: &mut Reader<'_>) -> Self { match r.get::() { true => Self::lower(r.get::().lift().into()), false => Self::lower(r.get::().lift().into()), } } fn write(self, w: &mut Writer) { w.put(self.v6); match self.lift() { std::net::IpAddr::V4(ip) => w.put(rt::Ipv4Addr::lower(ip)), std::net::IpAddr::V6(ip) => w.put(rt::Ipv6Addr::lower(ip)), } } } impl Wire for rt::SocketAddrV4 { fn read(r: &mut Reader<'_>) -> Self { Self { ip: r.get(), port: r.get(), } } fn write(self, w: &mut Writer) { w.put(self.ip); w.put(self.port); } } impl Wire for rt::SocketAddrV6 { fn read(r: &mut Reader<'_>) -> Self { Self { ip: r.get(), port: r.get(), flowinfo: r.get(), scope_id: r.get(), } } fn write(self, w: &mut Writer) { w.put(self.ip); w.put(self.port); w.put(self.flowinfo); w.put(self.scope_id); } } /// Whether it is IPv6, then the address of its family. impl Wire for rt::SocketAddr { fn read(r: &mut Reader<'_>) -> Self { match r.get::() { true => Self::lower(r.get::().lift().into()), false => Self::lower(r.get::().lift().into()), } } fn write(self, w: &mut Writer) { w.put(self.v6); match self.lift() { std::net::SocketAddr::V4(addr) => w.put(rt::SocketAddrV4::lower(addr)), std::net::SocketAddr::V6(addr) => w.put(rt::SocketAddrV6::lower(addr)), } } } impl Wire for rt::List { /// A view of the elements, as their length, or -1 for none, then each element, which /// the reader keeps. fn read(r: &mut Reader<'_>) -> Self { let Ok(len) = usize::try_from(r.get::()) else { return Self::NONE; }; // Rust only reads an array's items. let take = std::mem::replace(&mut r.take, false); let items: Box<[T]> = (0..len).map(|_| r.get()).collect(); r.take = take; let list = Self { ptr: items.as_ptr(), len, owner: std::ptr::null_mut(), }; r.arrays.push(Box::new(items)); list } fn write(self, w: &mut Writer) { if self.is_none() { w.put(-1i32); return; } let Ok(len) = i32::try_from(self.len) else { rt::fail("jni", "an array is too long for a List") }; w.put(len); // SAFETY: an array Rust returned, whose elements move into the writer, so it is // freed without them. unsafe { self.items("jni").iter().for_each(|&item| w.put(item)); Self { len: 0, ..self }.free("jni", |_| {}); } } } impl Wire for rt::Range { fn read(r: &mut Reader<'_>) -> Self { Self { start: r.get(), end: r.get(), } } fn write(self, w: &mut Writer) { w.put(self.start); w.put(self.end); } } impl Wire for rt::Bound { fn read(r: &mut Reader<'_>) -> Self { Self { kind: r.get(), value: r.get(), } } fn write(self, w: &mut Writer) { w.put(self.kind); w.put(self.value); } } impl Wire for rt::Bounds { fn read(r: &mut Reader<'_>) -> Self { Self { start: r.get(), end: r.get(), } } fn write(self, w: &mut Writer) { w.put(self.start); w.put(self.end); } }