Struct Global 

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

A global reference to a Java object.

Global references are slower to create and delete than ordinary local references, but have several properties that distinguish them:

• Global references are not bound to the lifetime of a Env.

• Global references are not bound to any particular thread; they have the Send and Sync traits.

• Until a global reference is dropped, it will prevent the referenced Java object from being garbage collected.

• It takes more time to create or delete a global reference than to create or delete a local reference.

These properties make global references useful in a few specific situations:

• When you need to keep a reference to the same Java object across multiple invocations of a native method, especially if you need a guarantee that it’s the exact same object every time, one way to do it is by storing a global reference to it in a Rust static variable.

• When you need to send a Java object reference to a different thread, or use a Java object reference from several different threads at the same time, a global reference can be used to do so.

• When you need a Java object to not be garbage collected too soon, because some side effect will happen (via java.lang.Object::finalize, java.lang.ref.Cleaner, or the like) when it is garbage collected, a global reference can be used to prevent it from being garbage collected. (This hold is released when the global reference is dropped.)

See also Weak, a global reference that does not prevent the underlying Java object from being garbage collected.

Creating and Deleting

To create a global reference, use the Env::new_global_ref method or wrap an existing global reference (that you own) with Env::global_from_raw. To delete it, simply drop the Global.

If you have a raw jobject global reference that you do not own, you can use Env::as_cast_raw to create a temporary wrapper that will not delete the reference when dropped.

Note that, because global references take more time to create or delete than local references do, they should only be used when their benefits outweigh this drawback. Also note that this performance penalty does not apply to using a global reference (such as calling methods on the underlying Java object), only to creation and deletion of the reference.

Warning: Drop On an Attached Thread If Possible

When a Global 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 Globals 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> Global<T>

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

pub fn null() -> Self

Creates a Global wrapper for a null reference

This is equivalent Global::default()

pub fn into_raw(self) -> jobject

Unwrap to the auto-delete global reference into a raw global jobject.

This prevents the global reference from being automatically deleted when this guard is dropped.

Leaking References

When unwrapping a Global you should consider how else you will ensure that the reference will get deleted.

The global reference may end up leaking unless a new Global wrapper is create later, or you find some way to call the JNI DeleteGlobalRef API on the raw reference.

Note: You should not find yourself unwrapping a raw global jobject that you do not logically own. If you have a raw global jobject that you do not own, you should instead use Env::as_cast_raw to create a temporary wrapper.

pub fn as_obj(&self) -> &JObject<'static>

Borrows a JObject referring to the same Java object as this Global.

This method is zero-cost and does not create a new local reference.

Global also implements AsRef<JObject>. That trait’s as_ref method does the same thing as this method.

Trait Implementations

impl<T, U> AsRef<U> for Global<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 Global<T>

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

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

Formats the value using the given formatter.

impl<T> Default for Global<T>

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

fn default() -> Self

Returns the “default value” for a type.

impl<T> Deref for Global<T>

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

type Target = T

The resulting type after dereferencing.

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

Dereferences the value.

impl<'local, 'obj_ref, T> Desc<'local, T> for &'obj_ref Global<T>

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

type Output = &'obj_ref T

The type that this Desc returns.

fn lookup(self, _: &mut Env<'local>) -> Result<Self::Output>

Look up the concrete type from the JVM.

impl<T> Drop for Global<T>

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

fn drop(&mut self)

Executes the destructor for this type.

impl<T> Reference for Global<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 Global<T>

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

impl<T> Sync for Global<T>

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