1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
use std::marker::PhantomData;
use crate::sys::jobject;
#[cfg(doc)]
use crate::{objects::GlobalRef, JNIEnv};
/// Wrapper around [`sys::jobject`] that adds a lifetime to ensure that
/// the underlying JNI pointer won't be accessible to safe Rust code if the
/// object reference is released.
///
/// It matches C's representation of the raw pointer, so it can be used in any
/// of the extern function argument positions that would take a `jobject`.
///
/// Most other types in the `objects` module deref to this, as they do in the C
/// representation.
///
/// The lifetime `'local` represents the local reference frame that this
/// reference belongs to. See the [`JNIEnv`] documentation for more information
/// about local reference frames. If `'local` is `'static`, then this reference
/// does not belong to a local reference frame, that is, it is either null or a
/// [global reference][GlobalRef].
///
/// Note that an *owned* `JObject` is always a local reference and will never
/// have the `'static` lifetime. [`GlobalRef`] does implement
/// <code>[AsRef]<JObject<'static>></code>, but this only yields a
/// *borrowed* `&JObject<'static>`, never an owned `JObject<'static>`.
///
/// Local references belong to a single thread and are not safe to share across
/// threads. This type implements [`Send`] and [`Sync`] if and only if the
/// lifetime `'local` is `'static`.
#[repr(transparent)]
#[derive(Debug)]
pub struct JObject<'local> {
internal: jobject,
lifetime: PhantomData<&'local ()>,
}
unsafe impl Send for JObject<'static> {}
unsafe impl Sync for JObject<'static> {}
impl<'local> AsRef<JObject<'local>> for JObject<'local> {
fn as_ref(&self) -> &JObject<'local> {
self
}
}
impl<'local> AsMut<JObject<'local>> for JObject<'local> {
fn as_mut(&mut self) -> &mut JObject<'local> {
self
}
}
impl<'local> ::std::ops::Deref for JObject<'local> {
type Target = jobject;
fn deref(&self) -> &Self::Target {
&self.internal
}
}
impl<'local> JObject<'local> {
/// Creates a [`JObject`] that wraps the given `raw` [`jobject`]
///
/// # Safety
///
/// `raw` may be a null pointer. If `raw` is not a null pointer, then:
///
/// * `raw` must be a valid raw JNI local reference.
/// * There must not be any other `JObject` representing the same local reference.
/// * The lifetime `'local` must not outlive the local reference frame that the local reference
/// was created in.
pub unsafe fn from_raw(raw: jobject) -> Self {
Self {
internal: raw,
lifetime: PhantomData,
}
}
/// Returns the raw JNI pointer.
pub fn as_raw(&self) -> jobject {
self.internal
}
/// Unwrap to the internal jni type.
pub fn into_raw(self) -> jobject {
self.internal
}
/// Creates a new null reference.
///
/// Null references are always valid and do not belong to a local reference frame. Therefore,
/// the returned `JObject` always has the `'static` lifetime.
pub fn null() -> JObject<'static> {
unsafe { JObject::from_raw(std::ptr::null_mut() as jobject) }
}
}
impl<'local> std::default::Default for JObject<'local> {
fn default() -> Self {
Self::null()
}
}