Struct Scope 

pub struct Scope<'scope> { /* private fields */ }

Handle passed to the closure body of Lua::scope.

Scope::create_userdata produces an AnyUserData whose backing storage is a borrow you provide; when the scope drops every cell it created is invalidated. Any later Lua call that reaches one of those userdatas fails with a clean error rather than touching freed memory.

Implementations

impl<'scope> Scope<'scope>

pub fn create_userdata_ref_mut<T>( &self, lua: &Lua, data: &'scope mut T, ) -> Result<AnyUserData>

where T: UserData,

Wrap a &mut T borrow as a Lua userdata that lives for the duration of this scope. Any call from Lua to the returned userdata after the scope ends fails with a clean Lua runtime error instead of touching the freed borrow.

Naming mirrors mlua’s Scope::create_userdata_ref_mut. The bare create_userdata name on Scope is intentionally reserved for the future by-value, non-'static constructor (mlua’s Scope::create_userdata<T: UserData + 'env>(T)), tracked as a follow-up to lua-rs#27.

Examples found in repository

examples/scope_world.rs (line 70)

fn main() -> Result<()> {
    let lua = Lua::new();
    let mut world = World::default();

    let count: i64 = lua.scope(|s| {
        let world_ud = s.create_userdata_ref_mut(&lua, &mut world)?;
        lua.globals().set("world", &world_ud)?;

        lua.load(
            r#"
            local a = world:spawn()
            local b = world:spawn()

            -- Direct mutation through a live sub-reference.
            local pa = world:position(a)
            pa.x, pa.y = 10, 20

            local pb = world:position(b)
            pb.x = pa.x + 5      -- reading pa here re-borrows; both are short-lived

            -- Stash one to prove it dies with the scope.
            escaped = world:position(a)

            return world:count()
        "#,
        )
        .eval()
    })?;

    println!("spawned {count} entities");
    // The mutations are visible to Rust after the scope returns.
    for (i, e) in world.entities.iter().enumerate() {
        println!("entity {i} = ({}, {})", e.x, e.y);
    }

    // The handle the script stashed on `escaped` is now invalid. Reading a
    // field raises a Lua error rather than touching the released `&mut World`.
    // We surface the message through Lua's own `pcall` + `tostring`, since the
    // error payload is a Lua value.
    let (ok, msg): (bool, String) = lua
        .load("local ok, e = pcall(function() return escaped.x end); return ok, tostring(e)")
        .eval()?;
    assert!(!ok, "stashed handle should be unusable after the scope");
    println!("post-scope use of a stashed handle -> {msg}");

    Ok(())
}

pub fn create_function<A, R, F>(&self, lua: &Lua, func: F) -> Result<Function>

where A: FromLuaMulti + 'static, R: IntoLuaMulti + 'static, F: Fn(&Lua, A) -> Result<R> + 'scope,

Build a Lua Function from a non-'static Rust closure. The closure is owned by a [ScopedFnCell] that the scope holds; once the scope drops, the cell drops the closure and any later Lua call that reaches the returned function fails cleanly with “no longer valid” instead of touching the released captures.

This is the function counterpart to [Self::create_userdata] — pair them when you want to hand Lua a &mut World plus a few closures that also borrow from the same stack frame.

pub fn create_function_mut<A, R, F>( &self, lua: &Lua, func: F, ) -> Result<Function>

where A: FromLuaMulti + 'static, R: IntoLuaMulti + 'static, F: FnMut(&Lua, A) -> Result<R> + 'scope,

Like Self::create_function but accepts an FnMut. Mirrors Lua::create_function_mut: re-entrant calls into the same closure are rejected with an “already borrowed” runtime error rather than producing aliasing &mut captures.

Trait Implementations

impl<'scope> Drop for Scope<'scope>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.