pub struct Vm { /* private fields */ }Expand description
The in-thread handle of a Lua VM run by this crate.
A Vm is a clone of the Lua handle; its state lives in the VM,
so every Vm of the same VM (from Vm::attach or Vm::of) sees
the same state. It holds the VM strongly: do not store it in
something the VM owns (a Lua function’s captured state, app data),
or the VM is never freed.
Implementations§
Source§impl Vm
impl Vm
Sourcepub fn attach(lua: &Lua, config: Config) -> Result<Vm, IsleError>
pub fn attach(lua: &Lua, config: Config) -> Result<Vm, IsleError>
Install the hook and store config.
Calling it again on the same VM re-installs the hook, replaces
the config (last wins) and returns a Vm for the same state; the
task table, if Vm::task_lib created it, is kept. Runs no Lua
code.
Hook callbacks registered before (with Vm::add_hook) are
kept.
The first attach also captures the xpcall global, which
[Vm::run] uses to bring a raised Lua value back as a value (see
LuaFailure). Attach before sandboxing the globals
(removing xpcall, or Lua::set_globals with a whitelist):
after that the capture is kept, and later changes to the globals
or a re-attach do not affect it.
The coroutine path needs mlua’s default
LuaOptions::catch_rust_panics = true. With false, mlua
replaces the global xpcall with a version that is not
yieldable, so every yield in a root run by [Vm::run] (an async
host function, task.join, preemption) fails with “attempt to
yield across a C-call boundary”. Lua::new uses the default.
§Errors
IsleError::Init with LuaErrorKind::External when the VM’s
xpcall global is not a function (it was sandboxed away before
the first attach).
Sourcepub fn set_config(&self, config: Config)
pub fn set_config(&self, config: Config)
Replace the VM’s settings. Takes effect for requests and tasks
that start afterwards (and, for preempt_every, at once).
Sourcepub fn add_hook<F>(
&self,
triggers: HookTriggers,
f: F,
) -> Result<HookId, IsleError>
pub fn add_hook<F>( &self, triggers: HookTriggers, f: F, ) -> Result<HookId, IsleError>
Register a hook callback, run from the VM’s hook after the cancel
check at triggers (see Hooks).
Instruction counts are approximated to the hook’s step (the
smallest count among all registrations and the cancel check).
Returning VmState::Yield yields the running coroutine,
including a coroutine the Lua code created itself, where the
yield reaches the Lua code’s coroutine.resume.
The callback applies to the main thread and to coroutines created
afterwards; coroutines that already exist keep the instruction
count and events they were created with. It is kept across a
second Vm::attach.
The callback is not re-entered. A callback that runs Lua code
can be hooked again from inside itself: resuming a coroutine is
the usual case, because the new thread has hooks enabled while
the hooked thread does not. That inner call fails with
mlua::Error::RecursiveMutCallback.
Known limit: a request’s Lua error goes through the crate’s
message handler (a C function under xpcall). Count and line
callbacks do not fire inside it, but a callback with on_calls /
on_returns fires for the handler’s own call and return. If
that callback returns Err, its error replaces the original Lua
error (the request fails with “error in error handling” or the
callback’s error). Do not fail from call / return callbacks if
the original error matters.
Sourcepub fn remove_hook(&self, id: HookId) -> Result<bool, IsleError>
pub fn remove_hook(&self, id: HookId) -> Result<bool, IsleError>
Remove a callback registered with Vm::add_hook. Returns
whether it was registered.
Trait Implementations§
Auto Trait Implementations§
impl !RefUnwindSafe for Vm
impl !Send for Vm
impl !Sync for Vm
impl !UnwindSafe for Vm
impl Freeze for Vm
impl Unpin for Vm
impl UnsafeUnpin for Vm
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> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
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