Make Lua::weak() method and WeakLua struct public.

This can be useful to prevent circular dependencies between Rust and Lua
or check that Lua instance is still alive.

Author: khvzak

src/lib.rs

@@ -104,7 +104,7 @@ pub use crate::function::{Function, FunctionInfo};
 pub use crate::hook::{Debug, DebugEvent, DebugNames, DebugSource, DebugStack};
 pub use crate::multi::{MultiValue, Variadic};
 pub use crate::scope::Scope;
-pub use crate::state::{GCMode, Lua, LuaOptions};
+pub use crate::state::{GCMode, Lua, LuaOptions, WeakLua};
 pub use crate::stdlib::StdLib;
 pub use crate::string::{BorrowedBytes, BorrowedStr, String};
 pub use crate::table::{Table, TablePairs, TableSequence};

src/prelude.rs

@@ -13,7 +13,7 @@ pub use crate::{
     UserData as LuaUserData, UserDataFields as LuaUserDataFields, UserDataMetatable as LuaUserDataMetatable,
     UserDataMethods as LuaUserDataMethods, UserDataRef as LuaUserDataRef,
     UserDataRefMut as LuaUserDataRefMut, UserDataRegistry as LuaUserDataRegistry, Value as LuaValue,
-    Variadic as LuaVariadic, VmState as LuaVmState,
+    Variadic as LuaVariadic, VmState as LuaVmState, WeakLua,
 };
 
 #[cfg(not(feature = "luau"))]

src/state.rs

@@ -55,8 +55,11 @@ pub struct Lua {
     pub(self) collect_garbage: bool,
 }
 
+/// Weak reference to Lua instance.
+///
+/// This can used to prevent circular references between Lua and Rust objects.
 #[derive(Clone)]
-pub(crate) struct WeakLua(XWeak<ReentrantMutex<RawLua>>);
+pub struct WeakLua(XWeak<ReentrantMutex<RawLua>>);
 
 pub(crate) struct LuaGuard(ArcReentrantMutexGuard<RawLua>);
 
@@ -1995,6 +1998,15 @@ impl Lua {
         LightUserData(&ASYNC_POLL_PENDING as *const u8 as *mut std::os::raw::c_void)
     }
 
+    /// Returns a weak reference to the Lua instance.
+    ///
+    /// This is useful for creating a reference to the Lua instance that does not prevent it from
+    /// being deallocated.
+    #[inline(always)]
+    pub fn weak(&self) -> WeakLua {
+        WeakLua(XRc::downgrade(&self.raw))
+    }
+
     // Luau version located in `luau/mod.rs`
     #[cfg(not(feature = "luau"))]
     fn disable_c_modules(&self) -> Result<()> {
@@ -2038,11 +2050,6 @@ impl Lua {
         LuaGuard(self.raw.lock_arc())
     }
 
-    #[inline(always)]
-    pub(crate) fn weak(&self) -> WeakLua {
-        WeakLua(XRc::downgrade(&self.raw))
-    }
-
     /// Returns a handle to the unprotected Lua state without any synchronization.
     ///
     /// This is useful where we know that the lock is already held by the caller.
@@ -2070,14 +2077,30 @@ impl WeakLua {
         Some(LuaGuard::new(self.0.upgrade()?))
     }
 
+    /// Upgrades the weak Lua reference to a strong reference.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the Lua instance is destroyed.
     #[track_caller]
     #[inline(always)]
-    pub(crate) fn upgrade(&self) -> Lua {
+    pub fn upgrade(&self) -> Lua {
         Lua {
             raw: self.0.upgrade().expect("Lua instance is destroyed"),
             collect_garbage: false,
         }
     }
+
+    /// Tries to upgrade the weak Lua reference to a strong reference.
+    ///
+    /// Returns `None` if the Lua instance is destroyed.
+    #[inline(always)]
+    pub fn try_upgrade(&self) -> Option<Lua> {
+        Some(Lua {
+            raw: self.0.upgrade()?,
+            collect_garbage: false,
+        })
+    }
 }
 
 impl PartialEq for WeakLua {

tests/tests.rs

@@ -12,6 +12,24 @@ use mlua::{
     UserData, Value, Variadic,
 };
 
+#[test]
+fn test_weak_lua() {
+    let lua = Lua::new();
+    let weak_lua = lua.weak();
+    assert!(weak_lua.try_upgrade().is_some());
+    drop(lua);
+    assert!(weak_lua.try_upgrade().is_none());
+}
+
+#[test]
+#[should_panic(expected = "Lua instance is destroyed")]
+fn test_weak_lua_panic() {
+    let lua = Lua::new();
+    let weak_lua = lua.weak();
+    drop(lua);
+    let _ = weak_lua.upgrade();
+}
+
 #[cfg(not(feature = "luau"))]
 #[test]
 fn test_safety() -> Result<()> {