Struct Jvm

#[repr(transparent)]
pub struct Jvm(pub &'static JavaVM);

Wrapper for the global JVM instance.

To obtain the instance, use Jvm::get_or_init() or Jvm::get().

Tuple Fields

0: &'static JavaVM

Implementations

impl Jvm

pub fn get_or_init() -> Result<Self>

Get the global singleton JVM instance, initializing it with the registered builder if not already initialized.

pub fn get() -> Option<Self>

Get the global singleton JVM instance, returning None if not initialized.

Use Jvm::get_or_init() if you want to initialize the JVM.

Methods from Deref<Target = JavaVM>

pub fn get_java_vm_pointer(&self) -> *mut *const JNIInvokeInterface_

Returns underlying sys::JavaVM interface.

pub fn attach_current_thread_permanently(&self) -> Result<JNIEnv<'_>, Error>

Attaches the current thread to the JVM. Calling this for a thread that is already attached is a no-op.

The thread will detach itself automatically when it exits.

Attached threads block JVM exit. If it is not desirable — consider using attach_current_thread_as_daemon.

pub fn attach_current_thread(&self) -> Result<AttachGuard<'_>, Error>

Attaches the current thread to the Java VM. The returned AttachGuard can be dereferenced to a JNIEnv and automatically detaches the thread when dropped. Calling this in a thread that is already attached is a no-op, and will neither change its daemon status nor prematurely detach it.

Attached threads block JVM exit.

Attaching and detaching a thread is an expensive operation. If you use it frequently in the same threads, consider either attaching them permanently, or, if the scope where you need the JNIEnv is well-defined, keeping the returned guard.

pub unsafe fn detach_current_thread(&self)

Explicitly detaches the current thread from the JVM.

Note: This operation is rarely appropriate to use, because the attachment methods ensure that the thread is automatically detached.

Detaching a non-attached thread is a no-op.

To support the use of JavaVM::destroy() it may be necessary to use this API to explicitly detach daemon threads before JavaVM::destroy() is called because JavaVM::destroy() does not synchronize and wait for daemon threads.

Any daemon thread that is still “attached” after JavaVM::destroy() returns would cause undefined behaviour if it then tries to make any JNI calls or tries to detach itself.

Normally jni-rs will automatically detach threads from the JavaVM by storing a guard in thread-local-storage that will detach on Drop but this will cause undefined behaviour if JavaVM::destroy() has been called.

Calling this will clear the thread-local-storage guard and detach the thread early to avoid any attempt to automatically detach when the thread exits.

Safety

Any existing JNIEnvs and AttachGuards created in the calling thread will be invalidated after this method completes. It is the caller’s responsibility to ensure that no JNI calls are subsequently performed on these objects. Failure to do so will result in unspecified errors, possibly, the process crash.

Given some care is exercised, this method can be used to detach permanently attached threads before they exit (when automatic detachment occurs). However, it is never appropriate to use it with the scoped attachment (attach_current_thread).

pub fn attach_current_thread_as_daemon(&self) -> Result<JNIEnv<'_>, Error>

Attaches the current thread to the Java VM as a daemon. Calling this in a thread that is already attached is a no-op, and will not change its status to a daemon thread.

The thread will detach itself automatically when it exits.

pub fn threads_attached(&self) -> usize

Returns the current number of threads attached to the JVM.

This method is provided mostly for diagnostic purposes.

pub fn get_env(&self) -> Result<JNIEnv<'_>, Error>

Get the JNIEnv associated with the current thread, or ErrorKind::Detached if the current thread is not attached to the java VM.

pub unsafe fn destroy(&self) -> Result<(), Error>

Unloads the JavaVM and frees all it’s associated resources

Firstly if this thread is not already attached to the JavaVM then it will be attached.

This thread will then wait until there are no other non-daemon threads attached to the JavaVM before unloading it (including threads spawned by Java and those that are attached via JNI)

Safety

IF YOU ARE USING DAEMON THREADS THIS MAY BE DIFFICULT TO USE SAFELY!

Daemon thread rules

Since the JNI spec makes it clear that DestroyJavaVM will not wait for attached deamon threads to exit, this also means that if you do have any attached daemon threads it is your responsibility to ensure that they don’t try and use JNI after the JavaVM is destroyed and you won’t be able to detach them after the JavaVM has been destroyed.

This creates a very unsafe hazard in jni-rs because it normally automatically ensures that any thread that gets attached will be detached before it exits.

Normally jni-rs will automatically detach threads from the JavaVM by storing a guard in thread-local-storage that will detach on Drop but this will cause undefined behaviour if JavaVM::destroy() has been called before the thread exits.

To clear this thread-local-storage guard from daemon threads you can call [JavaVM::detach_current_thread()] within each daemon thread, before calling this API.

Calling this will clear the thread-local-storage guard and detach the thread early to avoid any attempt to automatically detach when the thread exits.

Don’t call from a Java native function

There must be no Java methods on the call stack when JavaVM::destroy() is called.

Drop all JNI state, including auto-release types before calling JavaVM::destroy()

There is currently no 'vm lifetime associated with a JavaVM that would allow the borrow checker to enforce that all jni resources associated with the JavaVM have been released.

Since these JNI resources could lead to undefined behaviour through any use after the JavaVM has been destroyed then it is your responsibility to release these resources.

In particular, there are numerous auto-release types in the jni API that will automatically make JNI calls within their Drop implementation. All such types must be dropped before destroy() is called to avoid undefined bahaviour.

Here is an non-exhaustive list of auto-release types to consider:

• AttachGuard
• AutoElements
• AutoElementsCritical
• AutoLocal
• GlobalRef
• JavaStr
• JMap
• WeakRef

Invalid JavaVM on return

After destroy() returns then the JavaVM will be in an undefined state and must be dropped (e.g. via std::mem::drop()) to avoid undefined behaviour.

This method doesn’t take ownership of the JavaVM before it is destroyed because the JavaVM may have been shared (E.g. via an Arc) between all the threads that have not yet necessarily exited before this is called.

So although the JavaVM won’t necessarily be solely owned by this thread when destroy() is first called it will conceptually own the JavaVM before destroy() returns.

Trait Implementations

impl Clone for Jvm

fn clone(&self) -> Jvm

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Jvm

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

Formats the value using the given formatter.

impl Deref for Jvm

type Target = JavaVM

The resulting type after dereferencing.

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

Dereferences the value.

impl Copy for Jvm