[−][src]Struct rlua::prelude::Lua
Top level Lua struct which holds the Lua state itself.
Methods
impl Lua
[src]
pub fn new() -> Lua
[src]
Creates a new Lua state and loads standard library without the debug
library.
pub unsafe fn new_with_debug() -> Lua
[src]
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
[src]
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
[src]
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 fn load_from_std_lib(&self, lua_mod: StdLib) -> Result<()>
[src]
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<()>
[src]
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,
[src]
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 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() })?;
pub fn set_hook<F>(&self, triggers: HookTriggers, callback: F) where
F: 'static + Send + FnMut(Context, Debug) -> Result<()>,
[src]
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)
[src]
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
[src]
Returns the memory currently used inside this Lua state.
pub fn set_memory_limit(&self, memory_limit: Option<usize>)
[src]
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
[src]
Returns true if the garbage collector is currently running automatically.
pub fn gc_stop(&self)
[src]
Stop the Lua GC from running
pub fn gc_restart(&self)
[src]
Restarts the Lua GC if it is not running
pub fn gc_collect(&self) -> Result<()>
[src]
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>
[src]
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>
[src]
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
[src]
Sets the 'pause' value of the collector.
Returns the previous value of 'pause'. More information can be found in the Lua 5.3 documentation.
pub fn gc_set_step_multiplier(&self, step_multiplier: c_int) -> c_int
[src]
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.3 documentation.
Trait Implementations
Auto Trait Implementations
Blanket Implementations
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> From<T> for T
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,