Skip to main content

Isle

Struct Isle 

Source
pub struct Isle { /* private fields */ }
Expand description

Handle to a thread-isolated Lua VM.

Isle owns the communication channel and the join handle for the Lua thread. All operations are thread-safe (Isle: Send + Sync).

§Lifecycle

  1. Isle::spawn creates the Lua VM on a dedicated thread.
  2. Use eval, call, or exec to run code.
  3. shutdown sends a graceful stop signal and joins the thread.

If the Isle is dropped without calling shutdown, the channel disconnects and the Lua thread exits on its next receive attempt.

Implementations§

Source§

impl Isle

Source

pub fn spawn<F>(init: F) -> Result<Self, IsleError>
where F: FnOnce(&Lua) -> Result<(), Error> + Send + 'static,

Spawn a new Lua VM on a dedicated thread.

The init closure runs on the Lua thread before any requests are processed. Use it to register globals, install mlua-pkg resolvers, load mlua-batteries, etc.

§Errors

Returns IsleError::Init if the init closure fails (or the OS refuses to start the thread), and IsleError::ThreadPanic with the panic message if the init closure panics.

Source

pub fn eval<T>(&self, code: &str) -> Result<T, IsleError>
where T: FromLuaMulti + Send + 'static,

Evaluate a Lua chunk (blocking) and convert its return values to T. Equivalent to spawn_eval(code).wait().

The conversion (FromLuaMulti) runs on the Lua thread, so any T: FromLuaMulti + Send + 'static works: a single value (String, i64, f64, bool, BString for the raw bytes of a Lua string), () to ignore the result, Option<T> for a result that may be nil, or a tuple for several return values. Values tied to the VM (Table, Function, Value, MultiValue) are not Send without mlua’s send feature and then do not compile here; use exec to convert them on the Lua thread, or ask for a RegistryKey, which is Send, and read the value back in a later exec.

let isle = Isle::spawn(|_| Ok(())).unwrap();
let n: i64 = isle.eval("return 1 + 1").unwrap();
assert_eq!(n, 2);
let (a, b) = isle.eval::<(i64, String)>("return 1, 'x'").unwrap();
assert_eq!((a, b.as_str()), (1, "x"));
assert_eq!(isle.eval::<Option<String>>("return nil").unwrap(), None);

A Lua error is IsleError::Lua, and so is a return value that does not convert to T (kind Conversion). A FromLua of your own that fails with an error raised by Lua code it runs (a __index metamethod, say) is Lua with that error’s kind, not Conversion; the conversion runs under the request’s token, so a cancel while it runs Lua code is Cancelled. When the request’s token was cancelled, the result is IsleError::Cancelled even if the Lua code caught the cancel and raised an error of its own (the same rule as coroutine requests and Vm::run); this holds for call too.

Source

pub fn spawn_eval<T>(&self, code: &str) -> Task<T>
where T: FromLuaMulti + Send + 'static,

Evaluate a Lua chunk, returning a cancellable Task.

Source

pub fn call<A, T>(&self, func: &str, args: A) -> Result<T, IsleError>
where A: IntoLuaMulti + Send + 'static, T: FromLuaMulti + Send + 'static,

Call a named global Lua function (blocking) and convert its return values to T.

args is converted on the Lua thread (IntoLuaMulti): () for no arguments, a value, a tuple such as (1, true, "x"), or a Variadic for a number of arguments known only at run time (a Vec is one argument, a table). The result follows the rules of eval. A global that is not a function is IsleError::NotFound.

Source

pub fn spawn_call<A, T>(&self, func: &str, args: A) -> Task<T>
where A: IntoLuaMulti + Send + 'static, T: FromLuaMulti + Send + 'static,

Call a named global Lua function, returning a cancellable Task.

Source

pub fn exec<F, T>(&self, f: F) -> Result<T, IsleError>
where F: FnOnce(&Lua) -> Result<T, IsleError> + Send + 'static, T: Send + 'static,

Execute an arbitrary closure on the Lua thread (blocking).

The closure receives &Lua and can perform any operation; its T crosses back as is (no conversion). This is the escape hatch for complex interactions that don’t fit into eval or call, and the place to turn a value tied to the VM (a Table) into a Send one. ? works on mlua::Result inside the closure (IsleError: From<mlua::Error>).

Note: The cancel hook only fires during Lua instruction execution. If the closure blocks in Rust code (e.g. HTTP calls, file I/O), cancellation will not take effect until control returns to the Lua VM.

Source

pub fn spawn_exec<F, T>(&self, f: F) -> Task<T>
where F: FnOnce(&Lua) -> Result<T, IsleError> + Send + 'static, T: Send + 'static,

Execute a closure on the Lua thread, returning a cancellable Task.

Source

pub fn shutdown(self) -> Result<(), IsleError>

Graceful shutdown: signal the Lua thread to exit and join it.

After shutdown, all subsequent requests will return IsleError::Shutdown.

§Errors

IsleError::ThreadPanic if the Lua thread panicked (a request whose Rust code panicked ends the thread; that request itself returns IsleError::RecvFailed), with the panic message when the payload is a &str or a String.

Source

pub fn is_alive(&self) -> bool

Check if the Lua thread is still alive.

Trait Implementations§

Source§

impl Drop for Isle

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more

Auto Trait Implementations§

§

impl !Freeze for Isle

§

impl RefUnwindSafe for Isle

§

impl Send for Isle

§

impl Sync for Isle

§

impl Unpin for Isle

§

impl UnsafeUnpin for Isle

§

impl UnwindSafe for Isle

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

impl<T> MaybeSend for T

Source§

impl<T> MaybeSync for T

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.