Skip to main content

mlua_isle/
hooks.rs

1//! Deprecated: the hook API moved to [`runtime::Vm`].
2//!
3//! | 0.7 | 0.8 |
4//! |---|---|
5//! | `hooks::install(lua)` | [`Vm::attach(lua, config)`](crate::runtime::Vm::attach) |
6//! | `hooks::configure(lua, c)` | [`vm.set_config(c)`](crate::runtime::Vm::set_config) |
7//! | `hooks::config(lua)` | [`vm.config()`](crate::runtime::Vm::config) |
8//! | `hooks::add_hook(lua, t, f)` | [`vm.add_hook(t, f)`](crate::runtime::Vm::add_hook) |
9//! | `hooks::remove_hook(lua, id)` | [`vm.remove_hook(id)`](crate::runtime::Vm::remove_hook) |
10//! | `hooks::CancelConfig` | [`runtime::Config`] |
11//! | `hooks::HookId` | [`runtime::HookId`] |
12//!
13//! Every item here forwards to the `runtime` one and will be removed in
14//! the release after 0.8.0.  How the hook works is described in the
15//! [Hooks](crate::runtime#hooks) section of the `runtime` docs.
16
17use crate::error::IsleError;
18use crate::runtime::{self, Vm};
19use mlua::debug::Debug;
20use mlua::{HookTriggers, Lua, VmState};
21
22/// Handle of a hook callback.  Now [`runtime::HookId`].
23#[deprecated(since = "0.8.0", note = "use `mlua_isle::runtime::HookId`")]
24pub type HookId = runtime::HookId;
25
26/// Settings of a VM.  Now [`runtime::Config`], the same struct (this is
27/// an alias of it).
28#[deprecated(since = "0.8.0", note = "use `mlua_isle::runtime::Config`")]
29pub type CancelConfig = runtime::Config;
30
31/// Install (or re-install) the hook.  Forwards to [`Vm::attach`] with
32/// the VM's stored config (the default if none was set), so the VM is
33/// attached afterwards ([`Vm::of`] returns it).
34///
35/// # Errors
36///
37/// As [`Vm::attach`]: fails when the VM's `xpcall` global is not a
38/// function.
39#[deprecated(
40    since = "0.8.0",
41    note = "use `mlua_isle::runtime::Vm::attach(lua, config)`"
42)]
43pub fn install(lua: &Lua) -> Result<(), IsleError> {
44    Vm::attach(lua, crate::hub::config(lua)).map(drop)
45}
46
47/// Register a hook callback.  Attaches the VM with its stored config
48/// if it is not attached, then registers `callback` in the same hook as
49/// [`Vm::add_hook`], with the 0.7 semantics: an `Fn` callback that may
50/// be re-entered (`Vm::add_hook` takes an `FnMut` and is not
51/// re-entered).
52#[deprecated(since = "0.8.0", note = "use `mlua_isle::runtime::Vm::add_hook`")]
53pub fn add_hook<F>(
54    lua: &Lua,
55    triggers: HookTriggers,
56    callback: F,
57) -> Result<runtime::HookId, IsleError>
58where
59    F: Fn(&Lua, &Debug) -> mlua::Result<VmState> + 'static,
60{
61    runtime::of_or_attach(lua)?;
62    crate::hub::add_hook(lua, triggers, callback)
63}
64
65/// Remove a hook callback.  The same removal as [`Vm::remove_hook`];
66/// does not attach the VM.
67#[deprecated(since = "0.8.0", note = "use `mlua_isle::runtime::Vm::remove_hook`")]
68pub fn remove_hook(lua: &Lua, id: runtime::HookId) -> Result<bool, IsleError> {
69    crate::hub::remove_hook(lua, id)
70}
71
72/// Set the VM's settings.  Forwards to [`Vm::set_config`]; on a VM that
73/// is not attached yet it stores the config that the next
74/// [`Vm::attach`] of an actor keeps (it does not attach).
75#[deprecated(
76    since = "0.8.0",
77    note = "use `mlua_isle::runtime::Vm::set_config` (or pass the config to `Vm::attach`)"
78)]
79pub fn configure(lua: &Lua, config: runtime::Config) {
80    match Vm::of(lua) {
81        Some(vm) => vm.set_config(config),
82        None => crate::hub::set_config(lua, config),
83    }
84}
85
86/// The VM's settings.  Forwards to [`Vm::config`]; on a VM that is not
87/// attached yet it reads the stored config (the default if none was
88/// set).
89#[deprecated(since = "0.8.0", note = "use `mlua_isle::runtime::Vm::config`")]
90pub fn config(lua: &Lua) -> runtime::Config {
91    match Vm::of(lua) {
92        Some(vm) => vm.config(),
93        None => crate::hub::config(lua),
94    }
95}