Struct mlua::Lua

#[repr(transparent)]
pub struct Lua(_);

Top level Lua struct which represents an instance of Lua VM.

Implementations

impl Lua

pub fn new() -> Lua

Creates a new Lua state and loads the safe subset of the standard libraries.

Safety

The created Lua state would have some safety guarantees and would not allow to load unsafe standard libraries or C modules.

See StdLib documentation for a list of unsafe modules that cannot be loaded.

pub unsafe fn unsafe_new() -> Lua

Creates a new Lua state and loads all the standard libraries.

Safety

The created Lua state would not have safety guarantees and would allow to load C modules.

pub fn new_with(libs: StdLib, options: LuaOptions) -> Result<Lua>

Creates a new Lua state and loads the specified safe subset of the standard libraries.

Use the StdLib flags to specify the libraries you want to load.

Safety

The created Lua state would have some safety guarantees and would not allow to load unsafe standard libraries or C modules.

See StdLib documentation for a list of unsafe modules that cannot be loaded.

pub unsafe fn unsafe_new_with(libs: StdLib, options: LuaOptions) -> Lua

Creates a new Lua state and loads the specified subset of the standard libraries.

Use the StdLib flags to specify the libraries you want to load.

Safety

The created Lua state will not have safety guarantees and allow to load C modules.

pub unsafe fn init_from_ptr(state: *mut lua_State) -> Lua

Constructs a new Lua instance from an existing raw state.

Once called, a returned Lua state is cached in the registry and can be retrieved by calling this function again.

pub fn load_from_std_lib(&self, libs: StdLib) -> Result<()>

Loads the specified subset of the standard libraries into an existing Lua state.

Use the StdLib flags to specify the libraries you want to load.

pub fn load_from_function<'lua, S, T>(
    &'lua self,
    modname: &S,
    func: Function<'lua>
) -> Result<T>where
    S: AsRef<[u8]> + ?Sized,
    T: FromLua<'lua>,

Loads module modname into an existing Lua state using the specified entrypoint function.

Internally calls the Lua function func with the string modname as an argument, sets the call result to package.loaded[modname] and returns copy of the result.

If package.loaded[modname] value is not nil, returns copy of the value without calling the function.

If the function does not return a non-nil value then this method assigns true to package.loaded[modname].

Behavior is similar to Lua’s require function.

pub fn unload<S>(&self, modname: &S) -> Result<()>where
    S: AsRef<[u8]> + ?Sized,

Unloads module modname.

Removes module from the package.loaded table which allows to load it again. It does not support unloading binary Lua modules since they are internally cached and can be unloaded only by closing Lua state.

pub fn sandbox(&self, enabled: bool) -> Result<()>

Enables (or disables) sandbox mode on this Lua instance.

This method, in particular:

• Set all libraries to read-only
• Set all builtin metatables to read-only
• Set globals to read-only (and activates safeenv)
• Setup local environment table that performs writes locally and proxies reads to the global environment.

Examples

let lua = Lua::new();

lua.sandbox(true)?;
lua.load("var = 123").exec()?;
assert_eq!(lua.globals().get::<_, u32>("var")?, 123);

// Restore the global environment (clear changes made in sandbox)
lua.sandbox(false)?;
assert_eq!(lua.globals().get::<_, Option<u32>>("var")?, None);

Requires feature = "luau"

pub fn set_interrupt<F>(&self, callback: F)where
    F: 'static + MaybeSend + Fn() -> Result<VmState>,

Sets an ‘interrupt’ function that will periodically be called by Luau VM.

Any Luau code is guaranteed to call this handler “eventually” (in practice this can happen at any function call or at any loop iteration).

The provided interrupt function can error, and this error will be propagated through the Luau code that was executing at the time the interrupt was triggered. Also this can be used to implement continuous execution limits by instructing Luau VM to yield by returning VmState::Yield.

This is similar to [Lua::set_hook] but in more simplified form.

Example

Periodically yield Luau VM to suspend execution.

let lua = Lua::new();
let count = Arc::new(AtomicU64::new(0));
lua.set_interrupt(move || {
    if count.fetch_add(1, Ordering::Relaxed) % 2 == 0 {
        return Ok(VmState::Yield);
    }
    Ok(VmState::Continue)
});

let co = lua.create_thread(
    lua.load(r#"
        local b = 0
        for _, x in ipairs({1, 2, 3}) do b += x end
    "#)
    .into_function()?,
)?;
while co.status() == ThreadStatus::Resumable {
    co.resume(())?;
}

pub fn remove_interrupt(&self)

Removes any ‘interrupt’ previously set by set_interrupt.

This function has no effect if an ‘interrupt’ was not previously set.

pub fn inspect_stack(&self, level: usize) -> Option<Debug<'_>>

Gets information about the interpreter runtime stack.

This function returns Debug structure that can be used to get information about the function executing at a given level. Level 0 is the current running function, whereas level n+1 is the function that has called level n (except for tail calls, which do not count in the stack).

pub fn used_memory(&self) -> usize

Returns the amount of memory (in bytes) currently used inside this Lua state.

pub fn gc_is_running(&self) -> bool

Returns true if the garbage collector is currently running automatically.

Requires feature = "lua54/lua53/lua52/luau"

pub fn gc_stop(&self)

Stop the Lua GC from running

pub fn gc_restart(&self)

Restarts the Lua GC if it is not running

pub fn gc_collect(&self) -> Result<()>

Perform a full garbage-collection cycle.

It may be necessary to call this function twice to collect all currently unreachable objects. Once to finish the current gc cycle, and once to start and finish the next cycle.

pub fn gc_step(&self) -> Result<bool>

Steps the garbage collector one indivisible step.

Returns true if this has finished a collection cycle.

pub fn gc_step_kbytes(&self, kbytes: c_int) -> Result<bool>

Steps the garbage collector as though memory had been allocated.

if kbytes is 0, then this is the same as calling gc_step. Returns true if this step has finished a collection cycle.

pub fn gc_set_pause(&self, pause: c_int) -> c_int

Sets the ‘pause’ value of the collector.

Returns the previous value of ‘pause’. More information can be found in the Lua documentation.

For Luau this parameter sets GC goal

pub fn gc_set_step_multiplier(&self, step_multiplier: c_int) -> c_int

Sets the ‘step multiplier’ value of the collector.

Returns the previous value of the ‘step multiplier’. More information can be found in the Lua documentation.

pub fn gc_inc(
    &self,
    pause: c_int,
    step_multiplier: c_int,
    step_size: c_int
) -> GCMode

Changes the collector to incremental mode with the given parameters.

Returns the previous mode (always GCMode::Incremental in Lua < 5.4). More information can be found in the Lua documentation.

pub fn set_compiler(&self, compiler: Compiler)

Sets a default Luau compiler (with custom options).

This compiler will be used by default to load all Lua chunks including via require function.

See Compiler for details and possible options.

Requires feature = "luau"

pub fn load<'lua, 'a, S>(&'lua self, chunk: &'a S) -> Chunk<'lua, 'a>where
    S: AsChunk<'lua> + ?Sized,

Returns Lua source code as a Chunk builder type.

In order to actually compile or run the resulting code, you must call Chunk::exec or similar on the returned builder. Code is not even parsed until one of these methods is called.

pub fn create_string<S>(&self, s: &S) -> Result<String<'_>>where
    S: AsRef<[u8]> + ?Sized,

Create and return an interned Lua string. Lua strings can be arbitrary u8 data including embedded nulls, so in addition to &str and &String, you can also pass plain &[u8] here.

pub fn create_table(&self) -> Result<Table<'_>>

Creates and returns a new empty table.

pub fn create_table_with_capacity(
    &self,
    narr: c_int,
    nrec: c_int
) -> Result<Table<'_>>

Creates and returns a new empty table, with the specified capacity. narr is a hint for how many elements the table will have as a sequence; nrec is a hint for how many other elements the table will have. Lua may use these hints to preallocate memory for the new table.

pub fn create_table_from<'lua, K, V, I>(
    &'lua self,
    iter: I
) -> Result<Table<'lua>>where
    K: ToLua<'lua>,
    V: ToLua<'lua>,
    I: IntoIterator<Item = (K, V)>,

Creates a table and fills it with values from an iterator.

pub fn create_sequence_from<'lua, T, I>(
    &'lua self,
    iter: I
) -> Result<Table<'lua>>where
    T: ToLua<'lua>,
    I: IntoIterator<Item = T>,

Creates a table from an iterator of values, using 1.. as the keys.

pub fn create_function<'lua, A, R, F>(
    &'lua self,
    func: F
) -> Result<Function<'lua>>where
    A: FromLuaMulti<'lua>,
    R: ToLuaMulti<'lua>,
    F: 'static + MaybeSend + Fn(&'lua Lua, A) -> Result<R>,

Wraps a Rust function or closure, creating a callable Lua function handle to it.

The function’s return value is always a Result: If the function returns Err, the error is raised as a Lua error, which can be caught using (x)pcall or bubble up to the Rust code that invoked the Lua code. This allows using the ? operator to propagate errors through intermediate Lua code.

If the function returns Ok, the contained value will be converted to one or more Lua values. For details on Rust-to-Lua conversions, refer to the ToLua and ToLuaMulti traits.

Examples

Create a function which prints its argument:

let greet = lua.create_function(|_, name: String| {
    println!("Hello, {}!", name);
    Ok(())
});

Use tuples to accept multiple arguments:

let print_person = lua.create_function(|_, (name, age): (String, u8)| {
    println!("{} is {} years old!", name, age);
    Ok(())
});

pub fn create_function_mut<'lua, A, R, F>(
    &'lua self,
    func: F
) -> Result<Function<'lua>>where
    A: FromLuaMulti<'lua>,
    R: ToLuaMulti<'lua>,
    F: 'static + MaybeSend + FnMut(&'lua Lua, A) -> Result<R>,

Wraps a Rust mutable closure, creating a callable Lua function handle to it.

This is a version of create_function that accepts a FnMut argument. Refer to create_function for more information about the implementation.

pub unsafe fn create_c_function(
    &self,
    func: lua_CFunction
) -> Result<Function<'_>>

Wraps a C function, creating a callable Lua function handle to it.

Safety

This function is unsafe because provides a way to execute unsafe C function.

pub fn create_async_function<'lua, A, R, F, FR>(
    &'lua self,
    func: F
) -> Result<Function<'lua>>where
    A: FromLuaMulti<'lua>,
    R: ToLuaMulti<'lua>,
    F: 'static + MaybeSend + Fn(&'lua Lua, A) -> FR,
    FR: 'lua + Future<Output = Result<R>>,

Wraps a Rust async function or closure, creating a callable Lua function handle to it.

While executing the function Rust will poll Future and if the result is not ready, call yield() passing internal representation of a Poll::Pending value.

The function must be called inside Lua coroutine (Thread) to be able to suspend its execution. An executor should be used to poll AsyncThread and mlua will take a provided Waker in that case. Otherwise noop waker will be used if try to call the function outside of Rust executors.

The family of call_async() functions takes care about creating Thread.

Requires feature = "async"

Examples

Non blocking sleep:

use std::time::Duration;
use futures_timer::Delay;
use mlua::{Lua, Result};

async fn sleep(_lua: &Lua, n: u64) -> Result<&'static str> {
    Delay::new(Duration::from_millis(n)).await;
    Ok("done")
}

#[tokio::main]
async fn main() -> Result<()> {
    let lua = Lua::new();
    lua.globals().set("sleep", lua.create_async_function(sleep)?)?;
    let res: String = lua.load("return sleep(...)").call_async(100).await?; // Sleep 100ms
    assert_eq!(res, "done");
    Ok(())
}

pub fn create_thread<'lua>(
    &'lua self,
    func: Function<'lua>
) -> Result<Thread<'lua>>

Wraps a Lua function into a new thread (or coroutine).

Equivalent to coroutine.create.

pub fn create_userdata<T>(&self, data: T) -> Result<AnyUserData<'_>>where
    T: 'static + MaybeSend + UserData,

Create a Lua userdata object from a custom userdata type.

All userdata instances of type T shares the same metatable.

pub fn create_ser_userdata<T>(&self, data: T) -> Result<AnyUserData<'_>>where
    T: 'static + MaybeSend + UserData + Serialize,

Create a Lua userdata object from a custom serializable userdata type.

Requires feature = "serialize"

pub fn create_proxy<T>(&self) -> Result<AnyUserData<'_>>where
    T: 'static + UserData,

Create a Lua userdata “proxy” object from a custom userdata type.

Proxy object is an empty userdata object that has T metatable attached. The main purpose of this object is to provide access to static fields and functions without creating an instance of type T.

You can get or set uservalues on this object but you cannot borrow any Rust type.

Examples

struct MyUserData(i32);

impl UserData for MyUserData {
    fn add_fields<'lua, F: UserDataFields<'lua, Self>>(fields: &mut F) {
        fields.add_field_method_get("val", |_, this| Ok(this.0));
    }

    fn add_methods<'lua, M: UserDataMethods<'lua, Self>>(methods: &mut M) {
        methods.add_function("new", |_, value: i32| Ok(MyUserData(value)));
    }
}

lua.globals().set("MyUserData", lua.create_proxy::<MyUserData>()?)?;

lua.load("assert(MyUserData.new(321).val == 321)").exec()?;

pub fn globals(&self) -> Table<'_>

Returns a handle to the global environment.

pub fn current_thread(&self) -> Thread<'_>

Returns a handle to the active Thread. For calls to Lua this will be the main Lua thread, for parameters given to a callback, this will be whatever Lua thread called the callback.

pub fn scope<'lua, 'scope, R, F>(&'lua self, f: F) -> Result<R>where
    'lua: 'scope,
    R: 'static,
    F: FnOnce(&Scope<'lua, 'scope>) -> Result<R>,

Calls the given function with a Scope parameter, giving the function the ability to create userdata and callbacks from rust types that are !Send or non-’static.

The lifetime of any function or userdata created through Scope lasts only until the completion of this method call, on completion all such created values are automatically dropped and Lua references to them are invalidated. If a script accesses a value created through Scope outside of this method, a Lua error will result. Since we can ensure the lifetime of values created through Scope, and we know that Lua cannot be sent to another thread while Scope is live, it is safe to allow !Send datatypes and whose lifetimes only outlive the scope lifetime.

Inside the scope callback, all handles created through Scope will share the same unique ’lua lifetime of the parent Lua. This allows scoped and non-scoped values to be mixed in API calls, which is very useful (e.g. passing a scoped userdata to a non-scoped function). However, this also enables handles to scoped values to be trivially leaked from the given callback. This is not dangerous, though! After the callback returns, all scoped values are invalidated, which means that though references may exist, the Rust types backing them have dropped. Function types will error when called, and AnyUserData will be typeless. It would be impossible to prevent handles to scoped values from escaping anyway, since you would always be able to smuggle them through Lua state.

pub fn async_scope<'lua, 'scope, R, F, FR>(
    &'lua self,
    f: F
) -> LocalBoxFuture<'scope, Result<R>>where
    'lua: 'scope,
    R: 'static,
    F: FnOnce(Scope<'lua, 'scope>) -> FR,
    FR: 'scope + Future<Output = Result<R>>,

An asynchronous version of scope that allows to create scoped async functions and execute them.

Requires feature = "async"

pub fn coerce_string<'lua>(
    &'lua self,
    v: Value<'lua>
) -> Result<Option<String<'lua>>>

Attempts to coerce a Lua value into a String in a manner consistent with Lua’s internal behavior.

To succeed, the value must be a string (in which case this is a no-op), an integer, or a number.

pub fn coerce_integer(&self, v: Value<'_>) -> Result<Option<Integer>>

Attempts to coerce a Lua value into an integer in a manner consistent with Lua’s internal behavior.

To succeed, the value must be an integer, a floating point number that has an exact representation as an integer, or a string that can be converted to an integer. Refer to the Lua manual for details.

pub fn coerce_number(&self, v: Value<'_>) -> Result<Option<Number>>

Attempts to coerce a Lua value into a Number in a manner consistent with Lua’s internal behavior.

To succeed, the value must be a number or a string that can be converted to a number. Refer to the Lua manual for details.

pub fn pack<'lua, T: ToLua<'lua>>(&'lua self, t: T) -> Result<Value<'lua>>

Converts a value that implements ToLua into a Value instance.

pub fn unpack<'lua, T: FromLua<'lua>>(
    &'lua self,
    value: Value<'lua>
) -> Result<T>

Converts a Value instance into a value that implements FromLua.

pub fn pack_multi<'lua, T: ToLuaMulti<'lua>>(
    &'lua self,
    t: T
) -> Result<MultiValue<'lua>>

Converts a value that implements ToLuaMulti into a MultiValue instance.

pub fn unpack_multi<'lua, T: FromLuaMulti<'lua>>(
    &'lua self,
    value: MultiValue<'lua>
) -> Result<T>

Converts a MultiValue instance into a value that implements FromLuaMulti.

pub fn set_named_registry_value<'lua, S, T>(
    &'lua self,
    name: &S,
    t: T
) -> Result<()>where
    S: AsRef<[u8]> + ?Sized,
    T: ToLua<'lua>,

Set a value in the Lua registry based on a string name.

This value will be available to rust from all Lua instances which share the same main state.

pub fn named_registry_value<'lua, S, T>(&'lua self, name: &S) -> Result<T>where
    S: AsRef<[u8]> + ?Sized,
    T: FromLua<'lua>,

Get a value from the Lua registry based on a string name.

Any Lua instance which shares the underlying main state may call this method to get a value previously set by set_named_registry_value.

pub fn unset_named_registry_value<S>(&self, name: &S) -> Result<()>where
    S: AsRef<[u8]> + ?Sized,

Removes a named value in the Lua registry.

Equivalent to calling set_named_registry_value with a value of Nil.

pub fn create_registry_value<'lua, T: ToLua<'lua>>(
    &'lua self,
    t: T
) -> Result<RegistryKey>

Place a value in the Lua registry with an auto-generated key.

This value will be available to Rust from all Lua instances which share the same main state.

Be warned, garbage collection of values held inside the registry is not automatic, see RegistryKey for more details. However, dropped RegistryKeys automatically reused to store new values.

pub fn registry_value<'lua, T: FromLua<'lua>>(
    &'lua self,
    key: &RegistryKey
) -> Result<T>

Get a value from the Lua registry by its RegistryKey

Any Lua instance which shares the underlying main state may call this method to get a value previously placed by create_registry_value.

pub fn remove_registry_value(&self, key: RegistryKey) -> Result<()>

Removes a value from the Lua registry.

You may call this function to manually remove a value placed in the registry with create_registry_value. In addition to manual RegistryKey removal, you can also call expire_registry_values to automatically remove values from the registry whose RegistryKeys have been dropped.

pub fn replace_registry_value<'lua, T: ToLua<'lua>>(
    &'lua self,
    key: &RegistryKey,
    t: T
) -> Result<()>

Replaces a value in the Lua registry by its RegistryKey.

See create_registry_value for more details.

pub fn owns_registry_value(&self, key: &RegistryKey) -> bool

Returns true if the given RegistryKey was created by a Lua which shares the underlying main state with this Lua instance.

Other than this, methods that accept a RegistryKey will return Error::MismatchedRegistryKey if passed a RegistryKey that was not created with a matching Lua state.

pub fn expire_registry_values(&self)

Remove any registry values whose RegistryKeys have all been dropped.

Unlike normal handle values, RegistryKeys do not automatically remove themselves on Drop, but you can call this method to remove any unreachable registry values not manually removed by Lua::remove_registry_value.

pub fn set_app_data<T: 'static + MaybeSend>(&self, data: T)

Sets or replaces an application data object of type T.

Application data could be accessed at any time by using Lua::app_data_ref() or Lua::app_data_mut() methods where T is the data type.

Examples

use mlua::{Lua, Result};

fn hello(lua: &Lua, _: ()) -> Result<()> {
    let mut s = lua.app_data_mut::<&str>().unwrap();
    assert_eq!(*s, "hello");
    *s = "world";
    Ok(())
}

fn main() -> Result<()> {
    let lua = Lua::new();
    lua.set_app_data("hello");
    lua.create_function(hello)?.call(())?;
    let s = lua.app_data_ref::<&str>().unwrap();
    assert_eq!(*s, "world");
    Ok(())
}

pub fn app_data_ref<T: 'static>(&self) -> Option<Ref<'_, T>>

Gets a reference to an application data object stored by Lua::set_app_data() of type T.

pub fn app_data_mut<T: 'static>(&self) -> Option<RefMut<'_, T>>

Gets a mutable reference to an application data object stored by Lua::set_app_data() of type T.

pub fn remove_app_data<T: 'static>(&self) -> Option<T>

Removes an application data of type T.

Trait Implementations

impl Debug for Lua

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

Formats the value using the given formatter.

impl Deref for Lua

type Target = LuaInner

The resulting type after dereferencing.

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

Dereferences the value.

impl DerefMut for Lua

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'lua> LuaSerdeExt<'lua> for Lua

fn null(&'lua self) -> Value<'lua>

A special value (lightuserdata) to encode/decode optional (none) values.

fn array_metatable(&'lua self) -> Table<'lua>

A metatable attachable to a Lua table to systematically encode it as Array (instead of Map). As result, encoded Array will contain only sequence part of the table, with the same length as the # operator on that table.

fn to_value<T>(&'lua self, t: &T) -> Result<Value<'lua>>where
    T: Serialize + ?Sized,

Converts T into a Value instance.

fn to_value_with<T>(&'lua self, t: &T, options: Options) -> Result<Value<'lua>>where
    T: Serialize + ?Sized,

Converts T into a Value instance with options.

fn from_value<T>(&'lua self, value: Value<'lua>) -> Result<T>where
    T: Deserialize<'lua>,

Deserializes a Value into any serde deserializable object.

fn from_value_with<T>(
    &'lua self,
    value: Value<'lua>,
    options: Options
) -> Result<T>where
    T: Deserialize<'lua>,

Deserializes a Value into any serde deserializable object with options.

impl Send for Lua

Requires feature = "send"