Skip to main content

Vm

Struct Vm 

Source
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

Source

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).

Source

pub fn of(lua: &Lua) -> Option<Vm>

The Vm of lua, if Vm::attach was called on it.

Source

pub fn config(&self) -> Config

The VM’s settings.

Source

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).

Source

pub fn add_hook<F>( &self, triggers: HookTriggers, f: F, ) -> Result<HookId, IsleError>
where F: FnMut(&Lua, &Debug<'_>) -> Result<VmState> + 'static,

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.

Source

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§

Source§

impl Clone for Vm

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Vm

Source§

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

Formats the value using the given formatter. Read more

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> 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> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. 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> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
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.