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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
use std::{marker::PhantomData, mem::ManuallyDrop, ops::Deref, ptr::NonNull};
use crate::jvm::JavaObjectExt;
use crate::thread;
use crate::{cast::Upcast, plumbing::ObjectPtr, raw::EnvPtr, JavaObject};
/// An owned local reference to a non-null Java object of type `T`. The reference will be freed when
/// dropped. Cannot be shared across threads or [`Jvm::with`] invocations.
///
/// Locals cannot cross thread boundaries because they are not [`Send`]`:
/// ```compile_fail
/// fn check_send<T: Send>() {}
/// use duchess::{java, Local};
/// // Fails: `Local` is not `Send`
/// check_send::<Local<java::lang::String>>()
/// ```
#[derive_where::derive_where(PartialEq, Eq, Hash, Debug)]
pub struct Local<'jvm, T: JavaObject> {
env: EnvPtr<'jvm>,
obj: ObjectPtr,
_marker: PhantomData<T>,
}
impl<'jvm, T: JavaObject> Local<'jvm, T> {
/// Convert an existing local reference pointed to by `obj` into an owned `Local`. This is used by
/// codegen to wrap the output of most JNI calls to prevent the user from not freeing local refs.
///
/// # Safety
///
/// The caller must ensure that `obj` points to a Java object that is an instance of `T` (or its subclasses), is a
/// a live, local reference in the current frame, will not later be deleted (including through another call to
/// `from_raw()`), and will not dereferenced after the returned [`Local`] is dropped.
#[doc(hidden)]
pub unsafe fn from_raw(env: EnvPtr<'jvm>, obj: ObjectPtr) -> Self {
Self {
obj,
env,
_marker: PhantomData,
}
}
/// Creates a *new* local reference to `obj` in the current frame via a `NewLocalRef` JNI call.
pub(crate) fn new(env: EnvPtr<'jvm>, obj: &T) -> Self {
// SAFETY: The JavaObject trait contract ensures that &T points to a Java object that is an instance of T.
unsafe {
let new_ref = env.invoke_unchecked(
|jni| jni.NewLocalRef,
|jni, f| f(jni, obj.as_raw().as_ptr()),
);
Self::from_raw(env, NonNull::new(new_ref).unwrap().into())
}
}
/// Convert this `Local` into a raw object pointer *without* running the Local destructor (which would release it from the JVM).
///
/// # Safety
///
/// Caller must ensure that this pointer
/// does not escape the `'jvm` scope.
pub unsafe fn into_raw(self) -> ObjectPtr {
let p = self.as_raw();
std::mem::forget(self);
p
}
}
impl<T: JavaObject> Drop for Local<'_, T> {
fn drop(&mut self) {
// SAFETY: Local owns the local ref and it's no longer possible to dereference the object pointer.
unsafe {
self.env
.invoke_unchecked(|jni| jni.DeleteLocalRef, |jni, f| f(jni, self.obj.as_ptr()));
}
}
}
impl<T: JavaObject> Deref for Local<'_, T> {
type Target = T;
fn deref(&self) -> &Self::Target {
// SAFETY: from the guarantees of Local::from_raw, we know obj is a live local ref to an instance of T
unsafe { T::from_raw(self.obj) }
}
}
/// An owned reference to a non-null Java object of type `T`.
///
/// The JVM will not release this object until the Rust reference
/// is dropped.
#[derive_where::derive_where(PartialEq, Eq, Hash, Debug)]
pub struct Java<T: JavaObject> {
obj: ObjectPtr,
_marker: PhantomData<T>,
}
impl<T: JavaObject> Java<T> {
/// Convert an existing global reference pointed to by `obj` into an owned `Global`.
///
/// # Safety
///
/// The caller must ensure that `obj` points to a Java object that is an instance of `T` (or its subclasses), is a
/// a live, global reference, will not later be deleted (including through another call to `from_raw()`), and will
/// not dereferenced after the returned [`Global`] is dropped.
pub(crate) unsafe fn from_raw(obj: ObjectPtr) -> Self {
Self {
obj,
_marker: PhantomData,
}
}
/// Creates a *new* global reference to `obj` in the current frame via a `NewGlobalRef` JNI call.
pub(crate) fn new(env: EnvPtr<'_>, obj: &T) -> Self {
// SAFETY: The JavaObject trait contract ensures that &T points to a Java object that is an instance of T.
unsafe {
let new_ref =
env.invoke_unchecked(|e| e.NewGlobalRef, |e, f| f(e, obj.as_raw().as_ptr()));
Self::from_raw(NonNull::new(new_ref).unwrap().into())
}
}
}
impl<T: JavaObject> Drop for Java<T> {
fn drop(&mut self) {
let jvm = crate::jvm::unwrap_global_jvm();
// SAFETY: Global owns the global ref and it's no longer possible to dereference the object pointer.
let delete = |env: EnvPtr<'_>| unsafe {
env.invoke_unchecked(
|jni| jni.DeleteGlobalRef,
|jni, f| f(jni, self.obj.as_ptr()),
)
};
match unsafe { jvm.env() } {
Ok(Some(env)) => delete(env),
Ok(None) => {
// SAFETY: jvm is a valid pointer since duchess will not deinitialize a JVM once created
match unsafe { thread::attach(jvm) } {
Ok(mut attached) => delete(attached.env()),
Err(err) => {
tracing::warn!(?err, "unable to attach current thread to delete global ref")
}
}
}
Err(err) => tracing::warn!(
?err,
"unable to get JNI interface for local thread to delete global ref"
),
}
}
}
// SAFETY: The JNI promises only global refs are shareable across threads
unsafe impl<T: JavaObject> Send for Java<T> {}
unsafe impl<T: JavaObject> Sync for Java<T> {}
impl<T: JavaObject> Deref for Java<T> {
type Target = T;
fn deref(&self) -> &Self::Target {
// SAFETY: from the guarantees of Global::from_raw, we know obj is a live global ref to an instance of T
unsafe { T::from_raw(self.obj) }
}
}
impl<'a, R, S> AsRef<S> for Local<'a, R>
where
R: Upcast<S>,
S: JavaObject + 'a,
{
fn as_ref(&self) -> &S {
// SAFETY: From the Upcast trait contract, we know R is also an instance of S
unsafe { S::from_raw(self.obj) }
}
}
impl<'a, R: JavaObject> Local<'a, R> {
pub fn upcast<S>(self) -> Local<'a, S>
where
R: Upcast<S>,
S: JavaObject + 'a,
{
// From the Upcast trait contract, we know R is also an instance of S, so the invariant of _marker must be satisfied.
// We also need to ensure the Drop of Self does not run as that would free the underlying JVM local ref,
// causing a double-free when the upcasted Drop runs and frees the same local ref again.
let self_ = ManuallyDrop::new(self);
Local {
env: self_.env,
obj: self_.obj,
_marker: PhantomData
}
}
}
impl<R, S> AsRef<S> for Java<R>
where
R: Upcast<S>,
S: JavaObject + 'static,
{
fn as_ref(&self) -> &S {
// SAFETY: From the Upcast trait contract, we know R is also an instance of S
unsafe { S::from_raw(self.obj) }
}
}
impl<R: JavaObject> Java<R> {
pub fn upcast<S>(self) -> Java<S>
where
R: Upcast<S>,
S: JavaObject + 'static,
{
// From the Upcast trait contract, we know R is also an instance of S, so the invariant of _marker must be satisfied.
// We also need to ensure the Drop of Self does not run as that would free the underlying JVM global ref,
// causing a double-free when the upcasted Drop runs and frees the same global ref again.
let self_ = ManuallyDrop::new(self);
Java {
obj: self_.obj,
_marker: PhantomData,
}
}
}