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
Isle::spawncreates the Lua VM on a dedicated thread.- Use
eval,call, orexecto run code. shutdownsends 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
impl Isle
Sourcepub fn spawn<F>(init: F) -> Result<Self, IsleError>
pub fn spawn<F>(init: F) -> Result<Self, IsleError>
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.
Sourcepub fn eval<T>(&self, code: &str) -> Result<T, IsleError>where
T: FromLuaMulti + Send + 'static,
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.
Sourcepub fn spawn_eval<T>(&self, code: &str) -> Task<T>where
T: FromLuaMulti + Send + 'static,
pub fn spawn_eval<T>(&self, code: &str) -> Task<T>where
T: FromLuaMulti + Send + 'static,
Evaluate a Lua chunk, returning a cancellable Task.
Sourcepub fn call<A, T>(&self, func: &str, args: A) -> Result<T, IsleError>
pub fn call<A, T>(&self, func: &str, args: A) -> Result<T, IsleError>
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.
Sourcepub fn spawn_call<A, T>(&self, func: &str, args: A) -> Task<T>
pub fn spawn_call<A, T>(&self, func: &str, args: A) -> Task<T>
Call a named global Lua function, returning a cancellable Task.
Sourcepub fn exec<F, T>(&self, f: F) -> Result<T, IsleError>
pub fn exec<F, T>(&self, f: F) -> Result<T, IsleError>
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.
Sourcepub fn spawn_exec<F, T>(&self, f: F) -> Task<T>
pub fn spawn_exec<F, T>(&self, f: F) -> Task<T>
Execute a closure on the Lua thread, returning a cancellable Task.
Sourcepub fn shutdown(self) -> Result<(), IsleError>
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.
Trait Implementations§
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> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
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 moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
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