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}