pub struct WeakRef { /* private fields */ }
Expand description
A weak global JVM reference. These are global in scope like
GlobalRef
, and may outlive the JNIEnv
they came from, but are
not guaranteed to not get collected until released.
WeakRef
can be cloned to use the same weak reference in different
contexts. If you want to create yet another weak ref to the same java object, call
WeakRef::clone_in_jvm
.
Underlying weak reference will be dropped, when the last instance
of WeakRef
leaves its scope.
It is recommended that a native thread that drops the weak reference is attached
to the Java thread (i.e., has an instance of JNIEnv
). If the native thread is not attached,
the WeakRef#drop
will print a warning and implicitly attach
and detach
it, which
significantly affects performance.
Implementations§
source§impl WeakRef
impl WeakRef
sourcepub fn upgrade_local<'local>(
&self,
env: &JNIEnv<'local>
) -> Result<Option<JObject<'local>>>
pub fn upgrade_local<'local>( &self, env: &JNIEnv<'local> ) -> Result<Option<JObject<'local>>>
Creates a new local reference to this object.
This object may have already been garbage collected by the time this method is called. If
so, this method returns Ok(None)
. Otherwise, it returns Ok(Some(r))
where r
is the
new local reference.
If this method returns Ok(Some(r))
, it is guaranteed that the object will not be garbage
collected at least until r
is deleted or becomes invalid.
sourcepub fn upgrade_global(&self, env: &JNIEnv<'_>) -> Result<Option<GlobalRef>>
pub fn upgrade_global(&self, env: &JNIEnv<'_>) -> Result<Option<GlobalRef>>
Creates a new strong global reference to this object.
This object may have already been garbage collected by the time this method is called. If
so, this method returns Ok(None)
. Otherwise, it returns Ok(Some(r))
where r
is the
new strong global reference.
If this method returns Ok(Some(r))
, it is guaranteed that the object will not be garbage
collected at least until r
is dropped.
sourcepub fn is_garbage_collected(&self, env: &JNIEnv<'_>) -> Result<bool>
pub fn is_garbage_collected(&self, env: &JNIEnv<'_>) -> Result<bool>
Checks if the object referred to by this WeakRef
has been garbage collected.
Note that garbage collection can happen at any moment, so a return of Ok(true)
from this
method does not guarantee that WeakRef::upgrade_local
or WeakRef::upgrade_global
will succeed.
This is equivalent to
self.is_same_object(env, JObject::null())
.
sourcepub fn is_same_object<'local, O>(
&self,
env: &JNIEnv<'local>,
object: O
) -> Result<bool>where
O: AsRef<JObject<'local>>,
pub fn is_same_object<'local, O>( &self, env: &JNIEnv<'local>, object: O ) -> Result<bool>where O: AsRef<JObject<'local>>,
Returns true if this weak reference refers to the given object. Otherwise returns false.
If object
is null, then this method is equivalent to
WeakRef::is_garbage_collected
: it returns true if the object referred to by this
WeakRef
has been garbage collected, or false if the object has not yet been garbage
collected.
sourcepub fn is_weak_ref_to_same_object(
&self,
env: &JNIEnv<'_>,
other: &WeakRef
) -> Result<bool>
pub fn is_weak_ref_to_same_object( &self, env: &JNIEnv<'_>, other: &WeakRef ) -> Result<bool>
Returns true if this weak reference refers to the same object as another weak reference. Otherwise returns false.
This method will also return true if both weak references refer to an object that has been garbage collected.
sourcepub fn clone_in_jvm(&self, env: &JNIEnv<'_>) -> Result<Option<WeakRef>>
pub fn clone_in_jvm(&self, env: &JNIEnv<'_>) -> Result<Option<WeakRef>>
Creates a new weak reference to the same object that this one refers to.
WeakRef
implements Clone
, which should normally be used whenever a new WeakRef
to
the same object is needed. However, that only increments an internal reference count and
does not actually create a new weak reference in the JVM. If you specifically need to have
the JVM create a new weak reference, use this method instead of Clone
.
This method returns Ok(None)
if the object has already been garbage collected.