Struct rlua::Lua

pub struct Lua { /* private fields */ }

Top level Lua struct which holds the Lua state itself.

Implementations

impl Lua

pub fn new() -> Lua

Creates a new Lua state and loads standard library without the debug library.

pub unsafe fn new_with_debug() -> Lua

Creates a new Lua state and loads the standard library including the debug library.

The debug library is very unsound, it can be used to break the safety guarantees of rlua.

pub fn new_with(lua_mod: StdLib) -> Lua

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

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

Note that the debug library can’t be loaded using this function as it can be used to break the safety guarantees of rlua. If you really want to load it, use the sister function Lua::unsafe_new_with.

Panics

Panics if lua_mod contains StdLib::DEBUG

pub unsafe fn unsafe_new_with(lua_mod: StdLib) -> Lua

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

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

This function is unsafe because it can be used to load the debug library which can be used to break the safety guarantees provided by rlua.

pub unsafe fn unsafe_new_with_flags(
    lua_mod: StdLib,
    init_flags: InitFlags
) -> Lua

Creates a new Lua state with a subset of the standard libraries and modified initialization.

Use the StdLib flags to specifiy the libraries you want to load. Use the InitFlags to specify non-default Lua configuration.

unsafe_new_with_flags(mods, InitFlags::DEFAULT) is equivalent to unsafe_new_with(mods).

This function is unsafe because it can be used to load the debug library which can be used to break the safety guarantees provided by rlua, or to disable some of the safety features which rlua provides by default.

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

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

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

Note that the debug library can’t be loaded using this function as it can be used to break the safety guarantees of rlua. If you really want to load it, use the sister function Lua::unsafe_load_from_std_lib.

Panics

Panics if lua_mod contains StdLib::DEBUG

pub unsafe fn unsafe_load_from_std_lib(&self, lua_mod: StdLib) -> Result<()>

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

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

This function is unsafe because it can be used to load the debug library which can be used to break the safety guarantees provided by rlua.

pub fn context<F, R>(&self, f: F) -> R where
    F: FnOnce(Context<'_>) -> R, 

The main entry point of the rlua API.

In order to create Lua values, load and execute Lua code, or otherwise interact with the Lua state in any way, you must first call Lua::context and then call methods on the provided Context parameter.

rlua uses reference types like String and Table which reference shared data in the Lua state. These are special reference counted types that contain pointers to the main Lua state via the Context type, and there is a 'lua lifetime associated with these.

This 'lua lifetime is somewhat special. It is what is sometimes called a “generative” lifetime or a “branding” lifetime, which is invariant, and unique for each call to Lua::context.

The reason this entry point must be a callback is so that this unique lifetime can be generated as part of the callback’s parameters. Even though this callback API is somewhat inconvenient, it has several advantages:

• Inside calls to Lua::context, we know that all instances of the ’lua lifetime are the same unique lifetime. Thus, it is impossible for the user to accidentally mix handle types between different instances of Lua.
• Because we know at compile time that handles cannot be mixed from different instances of Lua, we do not need to do runtime checks to make sure that handles are from the same state.
• Handle types cannot escape the context call and the 'lua context lifetime is in general very limited, preventing it from being stored in unexpected places. This is a benefit as it helps ensure the soundness of the API.

It is not possible to return types with this 'lua context lifetime from the given callback, or store them outside of the callback in any way. There is an escape hatch here, though: if you need to keep references to internal Lua values long-term, you can use the Lua registry via Context::set_named_registry_value and Context::create_registry_value.

Examples

let lua = Lua::new();
lua.context(|lua_context| {
   lua_context.load(r#"
       print("hello world!")
   "#).exec()
})?;

pub fn set_hook<F>(&self, triggers: HookTriggers, callback: F) where
    F: 'static + Send + FnMut(Context<'_>, Debug<'_>) -> Result<()>, 

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_context, debug| {
    println!("line {}", debug.curr_line());
    Ok(())
});
lua.context(|lua_context| {
    lua_context.load(r#"
        local x = 2 + 3
        local y = x * 63
        local z = string.len(x..", "..y)
    "#).exec()
})?;

pub fn remove_hook(&self)

Remove any hook previously set by set_hook. This function has no effect if a hook was not previously set.

pub fn used_memory(&self) -> usize

Returns the memory currently used inside this Lua state.

pub fn set_memory_limit(&self, memory_limit: Option<usize>)

Sets a memory limit on this Lua state. Once an allocation occurs that would pass this memory limit, a Error::MemoryError is generated instead.

pub fn gc_is_running(&self) -> bool

Returns true if the garbage collector is currently running automatically.

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_inc(
    &self,
    pause: c_int,
    step_multiplier: c_int,
    step_size: c_int
) -> c_int

Sets the garbage collector to incremental mode.

Returns the previous mode (LUA_GCGEN or LUA_GCINC). More information can be found in the Lua 5.4 documentation.

pub fn gc_set_gen(
    &self,
    minor_multiplier: c_int,
    major_multiplier: c_int
) -> c_int

Sets the garbage collector to generational mode.

Returns the previous mode (LUA_GCGEN or LUA_GCINC). More information can be found in the Lua 5.4 documentation.

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

👎 Deprecated:

please use gc_set_inc instead

Sets the ‘pause’ value of the incremental collector.

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

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

👎 Deprecated:

please use gc_set_inc instead

Sets the ‘step multiplier’ value of the incremental collector.

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

Trait Implementations

impl Debug for Lua

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

Formats the value using the given formatter.

impl Default for Lua

fn default() -> Lua

Returns the “default value” for a type.

impl Drop for Lua

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Lua