Struct Weak 

pub struct Weak<T>
where
    T: Into<JObject<'static>> + AsRef<JObject<'static>> + Default + Reference + Send + Sync,
{ /* private fields */ }

A global reference to a Java object that does not prevent it from being garbage collected.

Weak global references have the same properties as ordinary “strong” global references, with one exception: a weak global reference does not prevent the referenced Java object from being garbage collected. In other words, the Java object can be garbage collected even if there is a weak global reference to it.

Upgrading

Because the Java object referred to by a weak global reference may be garbage collected at any moment, it cannot be directly used (such as calling methods on the referenced Java object). Instead, it must first be upgraded to a local or strong global reference, using the Weak::upgrade_local or Weak::upgrade_global method, respectively.

Both upgrade methods return an Option. If, when the upgrade method is called, the Java object has not yet been garbage collected, then the Option will be Some containing a newly created strong reference that can be used as normal. If not, the Option will be None.

Upgrading a weak global reference does not delete it. It is only deleted when the Weak is dropped, and it can be upgraded more than once.

Creating and Deleting

To create a weak global reference, use the Env::new_weak_ref method. To delete it, simply drop the Weak (but be sure to do so on an attached thread if possible; see the warning below).

It is also possible to create a new JNI weak global reference from an existing one. To do that, use the Weak::clone_in_jvm method.

Warning: Drop On an Attached Thread If Possible

When a Weak is dropped, a JNI call is made to delete the global reference. If this frequently happens on a thread that is not already attached to the JVM, the thread will be temporarily attached using JavaVM::attach_current_thread_for_scope, causing a severe performance penalty.

To avoid this performance penalty, ensure that Weaks are only dropped on a thread that is already attached (or never dropped at all).

In the event that a global reference is dropped on an unattached thread, a message is logged at log::Level::Warn.

Implementations

impl<T> Weak<T>

where T: Into<JObject<'static>> + AsRef<JObject<'static>> + Default + Reference + Send + Sync,

pub fn null() -> Self

Creates a Global wrapper for a null reference

This is equivalent Weak::default()

A null Weak acts as-if the object has been garbage collected (Self::is_garbage_collected() will return true).

pub fn as_raw(&self) -> jweak

Returns the raw JNI weak reference.

pub fn upgrade_local<'local>( &self, env: &mut Env<'local>, ) -> Result<Option<T::Kind<'local>>>

Creates a new local reference to this object.

This returns None if the object has already been garbage collected, otherwise it returns Some(new_local_reference).

If this method returns Some(r), it is guaranteed that the object will not be garbage collected at least until r is deleted or becomes invalid.

pub fn upgrade_global( &self, env: &Env<'_>, ) -> Result<Option<Global<T::GlobalKind>>>

Creates a new strong global reference to this object.

This returns None if the object has already been garbage collected, otherwise it returns Some(new_local_reference).

If this method returns Some(r), it is guaranteed that the object will not be garbage collected at least until r is deleted or becomes invalid.

pub fn is_garbage_collected(&self, env: &Env<'_>) -> Result<bool>

Checks if the object referred to by this Weak 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 Weak::upgrade_local or Weak::upgrade_global will succeed.

This is equivalent to self.is_same_object(env, JObject::null()).

This may return Error::JavaException if called while there is a pending exception.

pub fn is_same_object<'local, O>( &self, env: &Env<'local>, object: O, ) -> Result<bool>

where O: AsRef<JObject<'local>>,

👎Deprecated:

Use Env::is_same_object

Returns true if this weak reference refers to the given object. Otherwise returns false.

If object is null, then this method is equivalent to Weak::is_garbage_collected: it returns true if the object referred to by this Weak has been garbage collected, or false if the object has not yet been garbage collected.

pub fn is_weak_ref_to_same_object( &self, env: &Env<'_>, other: &Self, ) -> Result<bool>

👎Deprecated:

Use Env::is_same_object

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.

pub fn clone_in_jvm( &self, env: &mut Env<'_>, ) -> Result<Option<Weak<T::GlobalKind>>>

Creates a new weak reference to the same object that this one refers to.

This method returns None if the object has already been garbage collected.

Trait Implementations

impl<T, U> AsRef<U> for Weak<T>

where T: AsRef<U> + Into<JObject<'static>> + AsRef<JObject<'static>> + Default + Reference + Send + Sync,

fn as_ref(&self) -> &U

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> Debug for Weak<T>

where T: Into<JObject<'static>> + AsRef<JObject<'static>> + Default + Reference + Send + Sync + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Default for Weak<T>

where T: Into<JObject<'static>> + AsRef<JObject<'static>> + Default + Reference + Send + Sync,

fn default() -> Self

Returns the “default value” for a type.

impl<T> Deref for Weak<T>

where T: Into<JObject<'static>> + AsRef<JObject<'static>> + Default + Reference + Send + Sync,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T> Drop for Weak<T>

where T: Into<JObject<'static>> + AsRef<JObject<'static>> + Default + Reference + Send + Sync,

fn drop(&mut self)

Executes the destructor for this type.

impl<T> Reference for Weak<T>

where T: Into<JObject<'static>> + AsRef<JObject<'static>> + Default + Reference + Send + Sync,

type Kind<'env> = <T as Reference>::Kind<'env>

The generic associated Self::Kind type corresponds to the underlying class type (such as JObject or JString), parameterized by the lifetime that indicates whether the type holds a global reference ('static) or a local reference that’s tied to a JNI stack frame.

type GlobalKind = <T as Reference>::GlobalKind

The associated GlobalKind type should be equivalent to Kind<'static>, with the additional bound that ensures the type is Send + Sync

fn as_raw(&self) -> jobject

Returns the underlying, raw crate::sys::jobject reference.

fn class_name() -> Cow<'static, JNIStr>

The fully qualified class name of the Java class represented by this reference.

fn lookup_class<'caller>( env: &Env<'_>, loader_context: &LoaderContext<'_, '_>, ) -> Result<impl Deref<Target = Global<JClass<'static>>> + 'caller>

Looks up a global reference to the JClass associated with this reference.

unsafe fn kind_from_raw<'env>(local_ref: jobject) -> Self::Kind<'env>

Returns a new reference type based on Self::Kind for the given reference that is tied to the specified lifetime.

unsafe fn global_kind_from_raw(global_ref: jobject) -> Self::GlobalKind

Returns a ('static) reference type based on Self::GlobalKind for the given global_ref.

fn is_null(&self) -> bool

Returns true if this is a null object reference

fn null<'any>() -> Self::Kind<'any>

Returns null reference based on Self::Kind

impl<T> Send for Weak<T>

where T: Into<JObject<'static>> + AsRef<JObject<'static>> + Default + Reference + Send + Sync,

impl<T> Sync for Weak<T>

where T: Into<JObject<'static>> + AsRef<JObject<'static>> + Default + Reference + Send + Sync,