Struct Auto 

pub struct Auto<'local, T>
where
    T: Into<JObject<'local>>,
{ /* private fields */ }

A wrapper to Auto delete local references early (before the JNI stack frame unwinds).

---

Note that it’s often not necessary, or even recommended, to create an Auto wrapper for local JNI references if you can instead rely on the references being deleted when the current JNI stack frame unwinds.

---

Overview

Anything passed to a foreign method or returned from JNI methods that refers to a JObject is considered a local reference.

JNI local references belong to a JNI stack frame (the top frame at the time they are created).

These JNI references are normally automatically deleted once the their JNI stack frame unwinds, such as when a foreign method implementation returns back to the JavaVM.

In some situations you don’t want to wait until the current JNI stack frame unwinds before you delete a local reference and you can wrap then with Auto so they are deleted earlier, when they are dropped.

For example, you might be creating a very large number of temporary references in a loop that can lead to running out of memory if they aren’t explicitly deleted before the JNI stack frame unwinds.

This wrapper type provides automatic local reference deletion when it goes out of scope and gets dropped.

See also the JNI specification for details on referencing Java objects and some extra information.

IntoAuto trait (.auto())

As a convenience, the IntoAuto trait is implemented for all reference types (like JObject, JClass, JString etc). This allows you to easily create an Auto wrapper by calling the .auto() method on any local reference.

For example:

use jni::objects::IntoAuto as _;
for i in 0..1000 {
    // Ensure we aren't left with a new local for each iteration by
    // wrapping the reference in an `Auto` wrapper.
    let auto_delete_string = env.new_string("Hello, world!")?.auto();
}

Alternatives

It is usually more efficient to rely on stack frame unwinding to release local references in bulk instead of creating Auto wrappers that are then deleted one-by-one.

If you aren’t sure whether it’s OK to create new local references in the current JNI frame (perhaps because you don’t know when it will unwind) you can also consider using APIs like crate::Env::with_local_frame() which can run your code in a temporary stack frame that will release all local references in bulk, without needing to use Auto.

You can also explicitly delete a local reference with crate::Env::delete_local_ref.

Implementations

impl<'local, T> Auto<'local, T>

where T: Into<JObject<'local>>,

pub fn new(obj: T) -> Self

Creates a new auto-delete wrapper for a local ref.

Once this wrapper goes out of scope, the delete_local_ref will be called on the object. While wrapped, the object can be accessed via the Deref impl.

pub fn unwrap(self) -> T

Unwrap the RAII, auto-delete wrapper, returning the original local reference.

This prevents the local reference from being automatically deleted when this guard is dropped, and the local reference will instead get deleted when the JNI local frame holding the reference gets unwound.

Leaking References

When unwrapping an Auto you should consider how else you will ensure that the local reference will get released.

If you are implementing a native method then you may not need to keep an Auto wrapper since you can assume that when you return back to the Java VM then the local JNI stack frame will unwind and delete all local references.

Another option can be to use Env::with_local_frame or similar APIs that create a temporary JNI local frame where you can assume that all local references will be deleted when that local frame is unwound, after the given closure is called.

pub fn forget(self) -> T

👎Deprecated:

Renamed to Auto::unwrap

Unwrap the RAII, auto-delete wrapper, returning the original local reference.

See Self::unwrap

Trait Implementations

impl<'local, T, U> AsRef<U> for Auto<'local, T>

where T: AsRef<U> + Into<JObject<'local>>,

fn as_ref(&self) -> &U

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

impl<'local, T> Debug for Auto<'local, T>

where T: Into<JObject<'local>> + Debug,

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

Formats the value using the given formatter.

impl<'local, T> Deref for Auto<'local, T>

where T: Into<JObject<'local>>,

type Target = T

The resulting type after dereferencing.

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

Dereferences the value.

impl<'local, 'other_local, T> Desc<'local, T> for &Auto<'other_local, T>

where T: AsRef<T> + Into<JObject<'other_local>>,

type Output = &Auto<'other_local, 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<'local, 'other_local, T> Desc<'local, T> for Auto<'other_local, T>

where T: AsRef<T> + Into<JObject<'other_local>>,

type Output = Auto<'other_local, 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<'local, T> Drop for Auto<'local, T>

where T: Into<JObject<'local>>,

fn drop(&mut self)

Executes the destructor for this type.

impl<'local, T> From<T> for Auto<'local, T>

where T: Into<JObject<'local>>,

fn from(value: T) -> Self

Converts to this type from the input type.

impl<'local, T> Reference for Auto<'local, T>

where T: Reference + Into<JObject<'local>>,

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