Struct sandkiste_lua::v5_3::LuaMachine

pub struct LuaMachine<'a> { /* private fields */ }

Virtual machine that executes Lua code

Basic usage

1. A new virtual machine can be created with LuaMachine::new.
2. Use LuaMachine::load_stdlib_sealed to load a sealed version of the Lua standard library; that is a modified version which does not allow breaking out of the sandbox. Alternatively, a full version of the standard library can be loaded with LuaMachine::load_stdlib, which, for example, can be used to load further dependencies, and then be sealed afterwards with LuaMachine::seal. Note, however, that this may introduce security vulnerabilites depending on which libraries have been loaded or how the state has been modified prior to calling seal.
3. Set resource limits with LuaMachine::set_memory_limit and LuaMachine::set_execution_limit, if desired.
4. Use the API provided by the sandkiste crate to compile and execute Lua programs. For a concrete example using Lua, see the top-level module documentation of sandkiste_lua.

Lifetimes

Lifetime argument 'a is a lower bound for closures passed to the Lua machine. It can be inferred automatically.

Implementations

impl<'a> LuaMachine<'a>

pub fn new() -> Self

Create a bare Lua machine

pub fn lua_state(&self) -> *mut lua_State

Retrieve pointer to lua_State

pub fn assert_empty_stack(&self)

Assert that Lua stack is empty

pub fn set_execution_limit(&self, instr: u64)

Set limit for executed instructions

pub fn set_memory_limit(&self, bytes: usize)

Set memory limit

pub fn load_stdlib(&self) -> Result<(), MachineError>

Load standard library

pub fn load_stdlib_sealed(&self) -> Result<(), MachineError>

Load sealed version of standard library

pub fn seal(&self) -> Result<(), MachineError>

Remove certain parts of standard library to seal machine as sandbox

pub fn new_table<'b>( &'b self ) -> Result<LuaDatum<'a, 'b, 'static>, MachineError>

Create empty table

pub fn get_reference_key<'b>( &'b self, lua_ref: &LuaReference<'a, 'b> ) -> LuaReferenceKey

Get LuaReferenceKey for LuaReference

pub unsafe fn pop_error_message(&self) -> String

Pop error value from Lua stack and convert into String

pub unsafe fn pop_error(&self, status: c_int) -> Result<(), MachineError>

If status != LUA_OK, pop error value from Lua stack and convert into MachineError

pub unsafe fn pop_error_with_backtrace( &self, status: c_int ) -> Result<(), MachineError>

Same as LuaMachine::pop_error but also extract traceback (requires cmach_lua_errmsgh to be used during lua_pcall)

pub unsafe fn extract_datum<'b>( &'b self, index: c_int ) -> Result<LuaDatum<'a, 'b, 'static>, MachineError>

Convert value on Lua stack into LuaDatum

NOTE: requires some free space on Lua stack for operation

pub unsafe fn pop_datum<'b>( &'b self ) -> Result<LuaDatum<'a, 'b, 'static>, MachineError>

Pop value from Lua stack and convert into LuaDatum

NOTE: requires some free space on Lua stack for operation

pub unsafe fn push_reference<'b>(&'b self, lua_ref: &LuaReference<'a, 'b>)

Push LuaReference on top of Lua stack

pub unsafe fn push_bin(&self, binary: &[u8]) -> Result<(), MachineError>

Push binary data on top of Lua stack

NOTE: requires some free space on Lua stack for operation

pub unsafe fn push_str(&self, string: &str) -> Result<(), MachineError>

Push string on top of Lua stack

NOTE: requires some free space on Lua stack for operation

pub unsafe fn push_datum<'b, 'c>( &'b self, datum: &LuaDatum<'a, 'b, 'c> ) -> Result<(), MachineError>

Push LuaDatum on top of Lua stack

NOTE: requires some free space on Lua stack for operation

Trait Implementations

impl<'a> Callback<'a> for LuaMachine<'a>

fn callback<'b, 'c, F, R>( &'b self, func: F ) -> Result<LuaDatum<'a, 'b, 'static>, MachineError>where R: IntoIterator<Item = Self::Datum<'b, 'c>>, <R as IntoIterator>::IntoIter: ExactSizeIterator, F: 'a + Fn(Vec<LuaDatum<'a, 'b, 'static>>) -> Result<R, Box<dyn Error>>,

Create a Machine::Datum representing a callback (which invokes the func closure)

fn callback_expect_args<'b, 'c, F, R>( &'b self, argc: usize, func: F ) -> Result<Self::Datum<'b, 'static>, MachineError>where R: IntoIterator<Item = Self::Datum<'b, 'c>>, <R as IntoIterator>::IntoIter: ExactSizeIterator, F: 'a + Fn(Vec<Self::Datum<'b, 'static>, Global>) -> Result<R, Box<dyn Error + 'static, Global>>,

Same as Callback::callback but expects a fixed number of arguments

fn callback_expect_min_args<'b, 'c, F, R>( &'b self, argc: usize, func: F ) -> Result<Self::Datum<'b, 'static>, MachineError>where R: IntoIterator<Item = Self::Datum<'b, 'c>>, <R as IntoIterator>::IntoIter: ExactSizeIterator, F: 'a + Fn(Vec<Self::Datum<'b, 'static>, Global>) -> Result<R, Box<dyn Error + 'static, Global>>,

Same as Callback::callback but expects a minimum number of arguments

fn callback_1arg<'b, 'c, F, R>( &'b self, func: F ) -> Result<Self::Datum<'b, 'static>, MachineError>where R: IntoIterator<Item = Self::Datum<'b, 'c>>, <R as IntoIterator>::IntoIter: ExactSizeIterator, F: 'a + Fn(Self::Datum<'b, 'static>) -> Result<R, Box<dyn Error + 'static, Global>>,

Same as Callback::callback but expects exactly one argument

fn callback_2arg<'b, 'c, F, R>( &'b self, func: F ) -> Result<Self::Datum<'b, 'static>, MachineError>where R: IntoIterator<Item = Self::Datum<'b, 'c>>, <R as IntoIterator>::IntoIter: ExactSizeIterator, F: 'a + Fn(Self::Datum<'b, 'static>, Self::Datum<'b, 'static>) -> Result<R, Box<dyn Error + 'static, Global>>,

Same as Callback::callback but expects exactly two arguments

fn callback_3arg<'b, 'c, F, R>( &'b self, func: F ) -> Result<Self::Datum<'b, 'static>, MachineError>where R: IntoIterator<Item = Self::Datum<'b, 'c>>, <R as IntoIterator>::IntoIter: ExactSizeIterator, F: 'a + Fn(Self::Datum<'b, 'static>, Self::Datum<'b, 'static>, Self::Datum<'b, 'static>) -> Result<R, Box<dyn Error + 'static, Global>>,

Same as Callback::callback but expects exactly three arguments

fn callback_4arg<'b, 'c, F, R>( &'b self, func: F ) -> Result<Self::Datum<'b, 'static>, MachineError>where R: IntoIterator<Item = Self::Datum<'b, 'c>>, <R as IntoIterator>::IntoIter: ExactSizeIterator, F: 'a + Fn(Self::Datum<'b, 'static>, Self::Datum<'b, 'static>, Self::Datum<'b, 'static>, Self::Datum<'b, 'static>) -> Result<R, Box<dyn Error + 'static, Global>>,

Same as Callback::callback but expects exactly four arguments

fn callback_5arg<'b, 'c, F, R>( &'b self, func: F ) -> Result<Self::Datum<'b, 'static>, MachineError>where R: IntoIterator<Item = Self::Datum<'b, 'c>>, <R as IntoIterator>::IntoIter: ExactSizeIterator, F: 'a + Fn(Self::Datum<'b, 'static>, Self::Datum<'b, 'static>, Self::Datum<'b, 'static>, Self::Datum<'b, 'static>, Self::Datum<'b, 'static>) -> Result<R, Box<dyn Error + 'static, Global>>,

Same as Callback::callback but expects exactly five arguments

impl<'a, 'b> Compile<'a, &'b str> for LuaMachine<'a>

fn compile( &self, chunk_name: Option<String>, code: &'b str ) -> Result<LuaFunction<'a, '_>, MachineError>

Compiles code, returns the compiled function or a compilation error

impl<'a> Compile<'a, String> for LuaMachine<'a>

fn compile( &self, chunk_name: Option<String>, code: String ) -> Result<LuaFunction<'a, '_>, MachineError>

Compiles code, returns the compiled function or a compilation error

impl<'a> Debug for LuaMachine<'a>

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

Formats the value using the given formatter.

impl<'a> Drop for LuaMachine<'a>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a> Globals<'a> for LuaMachine<'a>

fn get<'b>( &'b self, name: &str ) -> Result<LuaDatum<'a, 'b, 'static>, MachineError>

Get global variable

fn set<'b, 'c>( &'b self, name: &str, value: LuaDatum<'a, 'b, 'c> ) -> Result<(), MachineError>

Set global variable

impl<'a> HasArray<'a> for LuaMachine<'a>

fn new_empty_array<'b>( &'b self ) -> Result<LuaDatum<'a, 'b, 'static>, MachineError>

Create datum that is an empty array

fn new_array<'b, 'c, I>( &'b self, elements: I ) -> Result<Self::Datum<'b, 'static>, MachineError>where I: IntoIterator<Item = Self::Datum<'b, 'c>>, Self::Datum<'b, 'static>: for<'d> MaybeArray<Element<'d> = Self::Datum<'b, 'd>>,

Create datum that is an array

impl<'a> HasModules<'a> for LuaMachine<'a>

type Module<'b> where 'a: 'b = LuaModule<'a, 'b>

Type of modules and sub-modules

fn module<'b>(&'b self, name: &str) -> Result<LuaModule<'a, 'b>, MachineError>

Open a module (create if non-existent)

impl<'a> HasStringMap<'a> for LuaMachine<'a>

fn new_empty_string_map<'b>( &'b self ) -> Result<LuaDatum<'a, 'b, 'static>, MachineError>

Create datum that is an empty string map

fn new_string_map<'b, 'c, 'd, I>( &'b self, entries: I ) -> Result<Self::Datum<'b, 'static>, MachineError>where I: IntoIterator<Item = (&'d str, Self::Datum<'b, 'c>)>, Self::Datum<'b, 'static>: for<'e> MaybeStringMap<Value<'e> = Self::Datum<'b, 'e>>,

Create datum that is a string map

impl<'a> Hash for LuaMachine<'a>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> Machine<'a> for LuaMachine<'a>

type Datum<'b, 'c> where Self: 'b = LuaDatum<'a, 'b, 'c>

Data type representing values passed to or returned from machine

type Function<'b> where Self: 'b = LuaFunction<'a, 'b>

Function (for example returned by Compile::compile) which can be executed by the machine

impl<'a> PartialEq<LuaMachine<'a>> for LuaMachine<'a>

A LuaMachine is only equal to itself

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> Eq for LuaMachine<'a>

A LuaMachine is only equal to itself