Struct mlua::prelude::Lua [−][src]
pub struct Lua { /* fields omitted */ }
Expand description
Top level Lua struct which holds the Lua state itself.
Implementations
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.
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.
Constructs a new Lua instance from an existing raw state.
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.
Consumes and leaks Lua
object, returning a static reference &'static Lua
.
This function is useful when the Lua
object is supposed to live for the remainder
of the program’s life.
In particular in asynchronous context this will allow to spawn Lua tasks to execute
in background.
Dropping the returned reference will cause a memory leak. If this is not acceptable,
the reference should first be wrapped with the Lua::from_static
function producing a Lua
.
This Lua
object can then be dropped which will properly release the allocated memory.
Constructs a Lua
from a static reference to it.
Safety
This function is unsafe because improper use may lead to memory problems or undefined behavior.
Sets a ‘hook’ function that will periodically be called as Lua code executes.
When exactly the hook function is called depends on the contents of the triggers
parameter, see HookTriggers
for more details.
The provided hook function can error, and this error will be propagated through the Lua code
that was executing at the time the hook was triggered. This can be used to implement a
limited form of execution limits by setting HookTriggers.every_nth_instruction
and
erroring once an instruction limit has been reached.
Example
Shows each line number of code being executed by the Lua interpreter.
let lua = Lua::new(); lua.set_hook(HookTriggers { every_line: true, ..Default::default() }, |_lua, debug| { println!("line {}", debug.curr_line()); Ok(()) })?; lua.load(r#" local x = 2 + 3 local y = x * 63 local z = string.len(x..", "..y) "#).exec()
Remove any hook previously set by set_hook
. This function has no effect if a hook was not
previously set.
Returns the amount of memory (in bytes) currently used inside this Lua state.
Sets a memory limit (in bytes) on this Lua state.
Once an allocation occurs that would pass this memory limit,
a Error::MemoryError
is generated instead.
Returns previous limit (zero means no limit).
Does not work on module mode where Lua state is managed externally.
Requires feature = "lua54/lua53/lua52"
Returns true if the garbage collector is currently running automatically.
Requires feature = "lua54/lua53/lua52"
Restarts the Lua GC if it is not running
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.
Steps the garbage collector one indivisible step.
Returns true if this has finished a collection cycle.
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.
Sets the ‘pause’ value of the collector.
Returns the previous value of ‘pause’. More information can be found in the Lua 5.3 documentation.
Sets the ‘step multiplier’ value of the collector.
Returns the previous value of the ‘step multiplier’. More information can be found in the Lua 5.x documentation.
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 5.x documentation.
Changes the collector to generational mode with the given parameters.
Returns the previous mode. More information about the generational GC can be found in the Lua 5.4 documentation.
Requires feature = "lua54"
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.
If this Lua
was created with unsafe_new
, load
will automatically detect and load
chunks of either text or binary type, as if passing bt
mode to luaL_loadbufferx
.
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.
Creates and returns a new empty 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)>,
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>,
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, 'callback, A, R, F>(
&'lua self,
func: F
) -> Result<Function<'lua>> where
'lua: 'callback,
A: FromLuaMulti<'callback>,
R: ToLuaMulti<'callback>,
F: 'static + MaybeSend + Fn(&'callback Lua, A) -> Result<R>,
pub fn create_function<'lua, 'callback, A, R, F>(
&'lua self,
func: F
) -> Result<Function<'lua>> where
'lua: 'callback,
A: FromLuaMulti<'callback>,
R: ToLuaMulti<'callback>,
F: 'static + MaybeSend + Fn(&'callback 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, 'callback, A, R, F>(
&'lua self,
func: F
) -> Result<Function<'lua>> where
'lua: 'callback,
A: FromLuaMulti<'callback>,
R: ToLuaMulti<'callback>,
F: 'static + MaybeSend + FnMut(&'callback Lua, A) -> Result<R>,
pub fn create_function_mut<'lua, 'callback, A, R, F>(
&'lua self,
func: F
) -> Result<Function<'lua>> where
'lua: 'callback,
A: FromLuaMulti<'callback>,
R: ToLuaMulti<'callback>,
F: 'static + MaybeSend + FnMut(&'callback 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 fn create_async_function<'lua, 'callback, A, R, F, FR>(
&'lua self,
func: F
) -> Result<Function<'lua>> where
'lua: 'callback,
A: FromLuaMulti<'callback>,
R: ToLuaMulti<'callback>,
F: 'static + MaybeSend + Fn(&'callback Lua, A) -> FR,
FR: 'lua + Future<Output = Result<R>>,
This is supported on crate feature async
only.
pub fn create_async_function<'lua, 'callback, A, R, F, FR>(
&'lua self,
func: F
) -> Result<Function<'lua>> where
'lua: 'callback,
A: FromLuaMulti<'callback>,
R: ToLuaMulti<'callback>,
F: 'static + MaybeSend + Fn(&'callback Lua, A) -> FR,
FR: 'lua + Future<Output = Result<R>>,
async
only.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(()) }
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,
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.
pub fn create_ser_userdata<T>(&self, data: T) -> Result<AnyUserData<'_>> where
T: 'static + MaybeSend + UserData + Serialize,
This is supported on crate feature serialize
only.
pub fn create_ser_userdata<T>(&self, data: T) -> Result<AnyUserData<'_>> where
T: 'static + MaybeSend + UserData + Serialize,
serialize
only.Create a Lua userdata object from a custom serializable userdata type.
Requires feature = "serialize"
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.
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>>,
This is supported on crate feature async
only.
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>>,
async
only.An asynchronous version of scope
that allows to create scoped async functions and
execute them.
Requires feature = "async"
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.
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.
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.
Converts a value that implements ToLua
into a Value
instance.
Converts a Value
instance into a value that implements FromLua
.
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>
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
.
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.
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
.
Removes a named value in the Lua registry.
Equivalent to calling set_named_registry_value
with a value of Nil.
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.
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
.
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
RegistryKey
s have been dropped.
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.
Remove any registry values whose RegistryKey
s have all been dropped.
Unlike normal handle values, RegistryKey
s 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
.
Trait Implementations
A special value (lightuserdata) to encode/decode optional (none) values. Read more
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. Read more
Converts T
into a Value
instance. Read more
Converts T
into a Value
instance with options. Read more
Deserializes a Value
into any serde deserializable object. Read more
Requires feature = "send"