pub struct Runtime { /* private fields */ }Expand description
The Lua runtime that provides an interface to execute Lua scripts and manage Lua state.
It allows for registering Rust extension modules on the nitr namespace,
running a configuration script, and calling Lua functions under the
state’s execution budget.
Implementations§
Source§impl Runtime
impl Runtime
Sourcepub fn eval_script(&self, path: &Path) -> Result<Value>
pub fn eval_script(&self, path: &Path) -> Result<Value>
Loads and evaluates a Lua script file, returning the resulting value.
This does not interpret the result; callers decide what the script is expected to return (e.g. a handler function or an application object).
Source§impl Runtime
impl Runtime
Sourcepub fn new() -> Result<Self>
pub fn new() -> Result<Self>
It creates a new Lua runtime with default options.
Such as some built-in libraries loaded and a default memory limit.
package is not among them, so require is unavailable: confinement
needs a directory to pin to, and this constructor takes no arguments to
name one. Embedders that want module loading call Runtime::new_with
with both StdLib::PACKAGE and a
package_dir.
Sourcepub fn new_with(opts: RuntimeOpts) -> Result<Self>
pub fn new_with(opts: RuntimeOpts) -> Result<Self>
It creates a new Lua runtime with specified options.
For example, it allows for customizing the Lua standard libraries to load
like io, math, os, etc as well as the memory limits.
Some scrubbing applies to every state, whatever the options:
collectgarbage is always removed (the memory limit is enforced by
the allocator, not the collector), and package-bearing states can
never load native modules — see
package_dir.
Sourcepub fn is_poisoned(&self) -> bool
pub fn is_poisoned(&self) -> bool
Whether a failure has left this state unfit for reuse (a memory limit hit or a caught panic). The pool rebuilds a poisoned state rather than handing it to the next request.
Sourcepub fn poison(&mut self)
pub fn poison(&mut self)
Marks this state unfit for reuse. Used by the HTTP layer when a panic is caught while the state is checked out.
Sourcepub fn register_module<F>(&self, name: &str, f: F) -> Result
pub fn register_module<F>(&self, name: &str, f: F) -> Result
Registers a Rust extension module: the closure runs now (and its
result is a table by Lua module convention), mounted at
nitr.ext.<name> — one level below the standard library, so a
module can never collide with a builtin. Fails when the name is
already taken, so two extensions cannot shadow each other.
This is the embedding-side extension point; HTTP applications use
ServerBuilder::module() in the nitr-http crate, which applies
the closure to every pooled state.
§Error attribution
An error a module raises should say which module failed. Wrap Rust
errors with a module <name> context and ErrorInfo classifies
them as kind = "module" with the module named; a module that
returns an opaque string makes its failures everyone’s problem:
t.set("query", lua.create_function(|_, sql: String| {
run(&sql).map_err(|err| mlua::Error::WithContext {
context: "module db".into(),
cause: std::sync::Arc::new(mlua::Error::external(err)),
})
})?)?;Sourcepub async fn register_cfg_fn(
&mut self,
cfg_src: &Path,
args: impl IntoLuaMulti,
) -> Result
pub async fn register_cfg_fn( &mut self, cfg_src: &Path, args: impl IntoLuaMulti, ) -> Result
It sets the Lua configuration script that runs once at server startup.
The script is a plain Lua chunk in the same shape handler scripts
use: statements at the top level ending in return { ... }, with
the provided arguments available as its varargs (local db = ...).
The Lua table containing the configuration fields can be accessed later
using the cfg() method.
Sourcepub fn lua(&self) -> &Lua
pub fn lua(&self) -> &Lua
The underlying Lua state, for advanced customization beyond
register_module().
Sourcepub fn cfg(&self) -> Option<&Table>
pub fn cfg(&self) -> Option<&Table>
The Lua configuration table that is returned after the script handler is invoked.
Sourcepub fn cfg_snapshot(&self) -> Result<Option<Value>>
pub fn cfg_snapshot(&self) -> Result<Option<Value>>
Serializes the configuration table into a plain-data snapshot that can
be injected into other runtimes with
set_cfg_snapshot().
Returns None when no configuration script has been registered.
Sourcepub fn set_cfg_snapshot(&mut self, snapshot: &Value) -> Result
pub fn set_cfg_snapshot(&mut self, snapshot: &Value) -> Result
Injects a configuration snapshot produced by
cfg_snapshot() as this runtime’s
configuration table.
Sourcepub async fn call_function<R: FromLuaMulti>(
&mut self,
f: Function,
args: impl IntoLuaMulti,
) -> Result<R>
pub async fn call_function<R: FromLuaMulti>( &mut self, f: Function, args: impl IntoLuaMulti, ) -> Result<R>
Calls a Lua function under the configured execution budget
(RuntimeOpts::exec_timeout): an instruction-count hook stops
CPU-bound overruns and an outer async timeout stops slow I/O
(Error::Timeout). The function runs on this runtime’s cached
coroutine so the instruction-count hook applies.
Sourcepub fn budgeted<R>(&self, f: impl FnOnce(&Lua) -> Result<R>) -> Result<R>
pub fn budgeted<R>(&self, f: impl FnOnce(&Lua) -> Result<R>) -> Result<R>
Runs f on this state under the execution budget, as a call is:
the load of a script has the same limits as the handlers in it.
Sourcepub async fn call_function_streaming<R: FromLuaMulti>(
&mut self,
f: Function,
args: impl IntoLuaMulti,
) -> Result<R>
pub async fn call_function_streaming<R: FromLuaMulti>( &mut self, f: Function, args: impl IntoLuaMulti, ) -> Result<R>
Calls a Lua function under the instruction-hook deadline only — no
outer async timeout — for long-lived streaming calls. The caller is
expected to keep granting budget via DeadlineHandle::extend() as
chunks are delivered; time suspended in async I/O (e.g. waiting for a
slow client) is deliberately unbounded.
Sourcepub fn deadline_handle(&self) -> DeadlineHandle
pub fn deadline_handle(&self) -> DeadlineHandle
A handle for extending this runtime’s execution deadline from
long-lived calls (see
call_function_streaming()).
Trait Implementations§
Auto Trait Implementations§
impl !Freeze for Runtime
impl !RefUnwindSafe for Runtime
impl !UnwindSafe for Runtime
impl Send for Runtime
impl Sync for Runtime
impl Unpin for Runtime
impl UnsafeUnpin for Runtime
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> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
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