Add Value::weak_lua helper

Close #714

Author: khvzak

src/buffer.rs

@@ -3,7 +3,7 @@ use std::io;
 #[cfg(feature = "serde")]
 use serde::ser::{Serialize, Serializer};
 
-use crate::state::RawLua;
+use crate::state::{RawLua, WeakLua};
 use crate::types::ValueRef;
 
 /// A Luau buffer type.
@@ -72,6 +72,13 @@ impl Buffer {
         BufferCursor(self, 0)
     }
 
+    /// Returns a weak reference to the Lua instance owning this value.
+    #[doc(hidden)]
+    #[inline]
+    pub fn weak_lua(&self) -> &WeakLua {
+        &self.0.lua
+    }
+
     pub(crate) fn as_slice(&self, lua: &RawLua) -> &[u8] {
         unsafe {
             let (buf, size) = self.as_raw_parts(lua);

src/function.rs

@@ -79,7 +79,7 @@ use std::result::Result as StdResult;
 use std::{mem, ptr, slice};
 
 use crate::error::{Error, ExternalError, ExternalResult, Result};
-use crate::state::Lua;
+use crate::state::{Lua, WeakLua};
 use crate::table::Table;
 use crate::traits::{FromLuaMulti, IntoLua, IntoLuaMulti};
 use crate::types::{Callback, LuaType, MaybeSend, ValueRef};
@@ -607,6 +607,13 @@ impl Function {
         self.0.to_pointer()
     }
 
+    /// Returns a weak reference to the Lua instance owning this value.
+    #[doc(hidden)]
+    #[inline]
+    pub fn weak_lua(&self) -> &WeakLua {
+        &self.0.lua
+    }
+
     /// Creates a deep clone of the Lua function.
     ///
     /// Copies the function prototype and all its upvalues to the

src/string.rs

@@ -9,7 +9,7 @@ use std::os::raw::{c_int, c_void};
 use std::{cmp, fmt, mem, slice, str};
 
 use crate::error::{Error, Result};
-use crate::state::Lua;
+use crate::state::{Lua, WeakLua};
 use crate::traits::IntoLua;
 use crate::types::{LuaType, ValueRef};
 use crate::value::Value;
@@ -154,6 +154,13 @@ impl LuaString {
         let lua = self.0.lua.lock();
         unsafe { ffi::lua_tostring(lua.ref_thread(), self.0.index) as *const c_void }
     }
+
+    /// Returns a weak reference to the Lua instance owning this value.
+    #[doc(hidden)]
+    #[inline]
+    pub fn weak_lua(&self) -> &WeakLua {
+        &self.0.lua
+    }
 }
 
 impl fmt::Debug for LuaString {

src/table.rs

@@ -795,6 +795,13 @@ impl Table {
         self.0.to_pointer()
     }
 
+    /// Returns a weak reference to the Lua instance owning this value.
+    #[doc(hidden)]
+    #[inline]
+    pub fn weak_lua(&self) -> &WeakLua {
+        &self.0.lua
+    }
+
     /// Returns an iterator over the pairs of the table.
     ///
     /// This works like the Lua `pairs` function, but does not invoke the `__pairs` metamethod.

src/thread.rs

@@ -40,7 +40,7 @@ use std::os::raw::{c_int, c_void};
 
 use crate::error::{Error, Result};
 use crate::function::Function;
-use crate::state::RawLua;
+use crate::state::{RawLua, WeakLua};
 use crate::traits::{FromLuaMulti, IntoLuaMulti};
 use crate::types::{LuaType, ValueRef};
 use crate::util::{StackGuard, check_stack, error_traceback_thread, pop_error};
@@ -774,6 +774,13 @@ impl Thread {
     pub fn to_pointer(&self) -> *const c_void {
         self.0.to_pointer()
     }
+
+    /// Returns a weak reference to the Lua instance owning this value.
+    #[doc(hidden)]
+    #[inline]
+    pub fn weak_lua(&self) -> &WeakLua {
+        &self.0.lua
+    }
 }
 
 impl fmt::Debug for Thread {

src/userdata.rs

@@ -11,7 +11,7 @@ use std::os::raw::{c_char, c_void};
 use crate::Either;
 use crate::error::{Error, Result};
 use crate::function::Function;
-use crate::state::Lua;
+use crate::state::{Lua, WeakLua};
 use crate::string::LuaString;
 use crate::table::{Table, TablePairs};
 use crate::traits::{FromLua, FromLuaMulti, IntoLua, IntoLuaMulti};
@@ -1028,6 +1028,13 @@ impl AnyUserData {
         self.0.to_pointer()
     }
 
+    /// Returns a weak reference to the Lua instance owning this value.
+    #[doc(hidden)]
+    #[inline]
+    pub fn weak_lua(&self) -> &WeakLua {
+        &self.0.lua
+    }
+
     /// Returns [`TypeId`] of this userdata if it is registered and `'static`.
     ///
     /// This method is not available for scoped userdata.

src/value.rs

@@ -7,6 +7,7 @@ use num_traits::FromPrimitive;
 
 use crate::error::{Error, Result};
 use crate::function::Function;
+use crate::state::WeakLua;
 use crate::string::LuaString;
 use crate::table::Table;
 use crate::thread::Thread;
@@ -178,6 +179,25 @@ impl Value {
         }
     }
 
+    /// Returns a weak reference to the Lua instance owning this value.
+    ///
+    /// Returns `None` for values without an associated Lua instance, such as primitive values
+    /// and [`Value::Error`].
+    #[inline]
+    pub fn weak_lua(&self) -> Option<&WeakLua> {
+        match self {
+            Value::String(s) => Some(s.weak_lua()),
+            Value::Table(t) => Some(t.weak_lua()),
+            Value::Function(f) => Some(f.weak_lua()),
+            Value::Thread(t) => Some(t.weak_lua()),
+            Value::UserData(ud) => Some(ud.weak_lua()),
+            #[cfg(feature = "luau")]
+            Value::Buffer(b) => Some(b.weak_lua()),
+            Value::Other(vref) => Some(&vref.lua),
+            _ => None,
+        }
+    }
+
     /// Returns `true` if the value is a [`Nil`].
     #[inline]
     pub fn is_nil(&self) -> bool {

tests/value.rs

@@ -237,6 +237,51 @@ fn test_value_to_string() -> Result<()> {
     Ok(())
 }
 
+#[test]
+fn test_value_weak_lua() -> Result<()> {
+    let lua = Lua::new();
+    let values = [
+        Value::String(lua.create_string("hello")?),
+        Value::Table(lua.create_table()?),
+        Value::Function(lua.create_function(|_, ()| Ok(()))?),
+        Value::Thread(lua.create_thread(lua.create_function(|_, ()| Ok(()))?)?),
+        Value::UserData(lua.create_any_userdata(())?),
+        #[cfg(feature = "luau")]
+        Value::Buffer(lua.create_buffer(b"hello")?),
+    ];
+
+    for value in &values {
+        let weak = value.weak_lua().expect("reference value has a Lua instance");
+        assert!(weak == &lua.weak());
+        let upgraded = weak.try_upgrade().expect("Lua instance is alive");
+        upgraded.globals().set("weak_lua_test", true)?;
+        assert!(lua.globals().get::<bool>("weak_lua_test")?);
+    }
+
+    drop(lua);
+    for value in &values {
+        let weak = value
+            .weak_lua()
+            .expect("destroyed instance still has a weak handle");
+        assert!(weak.try_upgrade().is_none());
+    }
+
+    for value in [
+        Value::Nil,
+        Value::Boolean(true),
+        Value::NULL,
+        Value::Integer(1),
+        Value::Number(1.0),
+        Value::Error(Box::new(Error::runtime("test"))),
+        #[cfg(feature = "luau")]
+        Value::Vector(mlua::Vector::default()),
+    ] {
+        assert!(value.weak_lua().is_none());
+    }
+
+    Ok(())
+}
+
 #[test]
 fn test_debug_format() -> Result<()> {
     let lua = Lua::new();