Struct rlua::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 standard library without the debug
library.
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.
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
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.
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
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.
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 ofLua
. - 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()
})?;
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()
})?;
Remove any hook previously set by set_hook
. This function has no effect if a hook was not
previously set.
Returns the memory currently used inside this Lua state.
Sets a memory limit on this Lua state. Once an allocation occurs that would pass this
memory limit, a Error::MemoryError
is generated instead.
Returns true if the garbage collector is currently running automatically.
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 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.
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.
👎 Deprecated: please use gc_set_inc
instead
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.
👎 Deprecated: please use gc_set_inc
instead
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.