Struct rlua::Lua

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

source

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.

source

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.

source

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

source

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.

source

pub fn context<F, R>(&self, f: F) -> Rwhere 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()
})?;

source

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()
})?;

source

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.

source

pub fn used_memory(&self) -> usize

Returns the memory currently used inside this Lua state.

source

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.

source

pub fn gc_is_running(&self) -> bool

Returns true if the garbage collector is currently running automatically.

source

pub fn gc_stop(&self)

Stop the Lua GC from running

source

pub fn gc_restart(&self)

Restarts the Lua GC if it is not running

source

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.

source