Struct RuntimeEngine 

pub struct RuntimeEngine { /* private fields */ }

Implementations

impl RuntimeEngine

pub fn new() -> Self

Create a runtime with all built-in primitive descriptors.

Panics

Panics only if a compile-time built-in descriptor violates the same validation rules enforced for downstream custom primitives.

pub fn compile(&mut self, source: &str) -> Result<CompiledUi, RuntimeError>

Compile the default application entry source.

Errors

Returns RuntimeError::Compile when Rhai rejects the source.

pub fn compile_named( &mut self, source_name: &str, source: &str, ) -> Result<CompiledUi, RuntimeError>

Compile source with an explicit diagnostic name and advance the script generation.

Errors

Returns RuntimeError::Compile when Rhai rejects the source.

pub fn compile_self_contained_named( &mut self, source_name: &str, source: &str, ) -> Result<CompiledUi, RuntimeError>

Compile source while eagerly resolving and embedding literal imports.

Errors

Returns RuntimeError::Compile for source, import, or module errors.

pub fn set_module_resolver(&mut self, resolver: impl ModuleResolver + 'static)

pub fn with_program_preparation<T, E>( &mut self, operation: impl FnOnce(&mut Self) -> Result<T, E>, ) -> Result<T, E>

Compile all modules and the entry AST for one candidate under one unique program identity. Independent calls receive different generations even when neither candidate has been rendered yet.

Errors

Returns the error produced by operation.

pub fn render(&mut self, compiled: &CompiledUi) -> Result<UiNode, RuntimeError>

Evaluate the compiled application’s view function.

Errors

Returns RuntimeError::Evaluate when view is missing, fails, or returns a value other than UiNode.

pub fn render_with_context( &mut self, compiled: &CompiledUi, context: UiContext, ) -> Result<UiNode, RuntimeError>

Evaluate the compiled application’s view(ctx) function.

Errors

Returns RuntimeError::Evaluate when view fails or returns a value other than UiNode.

pub fn call_optional_lifecycle( &self, compiled: &CompiledUi, function: &str, context: UiContext, ) -> Result<bool, RuntimeError>

Invoke an optional one-argument lifecycle function.

Errors

Returns RuntimeError::Evaluate when the function exists but fails.

pub fn root_state_schema( &self, compiled: &CompiledUi, ) -> Result<ComponentStateSchema, RuntimeError>

Decode optional root state_schema() from an application entry.

Errors

Returns RuntimeError::Evaluate when the function fails or cannot be decoded as ComponentStateSchema.

pub fn callback( &self, compiled: &CompiledUi, function_name: &str, ) -> Result<ScriptCallback, RuntimeError>

Create a generation-bound callback for a script function.

Errors

Returns RuntimeError::CallbackDefinition when the function name is not a valid Rhai function pointer name.

pub fn invoke_callback( &self, compiled: &CompiledUi, callback: &ScriptCallback, args: impl FuncArgs, ) -> Result<Dynamic, RuntimeError>

Invoke a callback only when it belongs to the current compiled generation.

Errors

Returns RuntimeError::StaleCallback for obsolete callbacks and RuntimeError::Evaluate when the Rhai function fails.

pub fn is_current(&self, generation: ScriptGeneration) -> bool

pub fn engine(&self) -> &Engine

pub fn definition_source(&self) -> String

Generate the official Rhai language-server definition source for every function/type/module registered on this engine.

Standard packages are omitted because the language server supplies them.

pub fn lint_known_calls( &mut self, entry_name: &str, entry_source: &str, modules: &BTreeMap<ModuleId, String>, ) -> Result<Vec<KnownCallDiagnostic>, KnownCallLintError>

Validate statically visible direct and method call arities in an entry script and its installed modules.

This complements real lifecycle execution because Rhai resolves functions dynamically and an initial render cannot cover every branch. The catalog comes from the same registered Engine metadata used by Self::definition_source.

Errors

Returns a metadata or parse error if the lint catalog cannot be built.

pub fn component_exports( &self, ) -> Result<ComponentRegistry, ComponentExportError>

Return a snapshot of components exported through this engine.

Errors

Returns ComponentExportError if the export registry was poisoned by a prior panic.

pub fn component_invocations( &self, ) -> impl ExactSizeIterator<Item = &ComponentInvocationRecipe>

pub fn clear_component_exports(&self) -> Result<(), ComponentExportError>

Clear component exports before evaluating a hot-reload candidate.

Errors

Returns ComponentExportError if the collector is unavailable.

pub fn restore_component_exports( &self, registry: ComponentRegistry, ) -> Result<(), ComponentExportError>

Restore a prior export snapshot after a rejected candidate.

Errors

Returns ComponentExportError if the collector is unavailable.

pub fn register_primitive( &mut self, descriptor: PrimitiveDescriptor, handler: impl PrimitiveHandler + 'static, ) -> Result<(), PrimitiveError>

Register a namespaced Rust custom primitive and its Rhai constructor.

Errors

Returns PrimitiveError when the descriptor conflicts or is invalid.

pub fn primitive_registry(&self) -> PrimitiveRegistry

pub fn register_native_handler( &self, descriptor: NativeHandlerDescriptor, handler: impl FnMut(NativeEvent, &mut UiRuntimeState, &mut Window, &mut App) -> Result<EventResponse, String> + 'static, ) -> Result<(), NativeHandlerError>

Register a trusted Rust handler attachable by Rhai through native_handler.

Errors

Returns descriptor/duplicate registry errors.

pub fn native_handler_registry(&self) -> NativeHandlerRegistry

pub fn syntax_registry(&self) -> SyntaxRegistry

pub fn document_runtime_config(&self) -> DocumentRuntimeConfig

pub fn set_slow_threshold(&mut self, threshold: Duration)

pub fn set_operation_limit(&mut self, limit: u64)

Set the per-execution script operation budget.

The default is DEFAULT_SCRIPT_OPERATION_LIMIT. This is a cumulative operation quota for each execution round, not a frame-time guarantee. A host that runs known one-shot, cacheable script phases (a layout pass, an analysis sweep) may raise it; the wall-clock slow threshold still flags anything that stalls the foreground. Scripts cannot change this limit; only the embedding application can. Zero normalizes to one; it never disables protection. Changes apply to subsequent calls. Native Rust work is not preempted by this quota.

pub fn operation_limit(&self) -> u64

The per-execution script operation budget in force.

pub fn set_expression_depth_limits(&mut self, global: usize, functions: usize)

Configure parser depth independently of execution/recursion/data limits. Defaults are global=64/function=32 in both debug and release. Zero normalizes to one rather than adopting Rhai’s unlimited convention.

pub fn expression_depth_limits(&self) -> (usize, usize)

pub fn take_timings(&self) -> Vec<ExecutionTiming>

pub fn last_failed_timing(&self) -> Option<ExecutionTiming>

Return the failed timing from the current execution session, if any. Starting the next compile, render, callback, or lifecycle call clears it.

Trait Implementations

impl Default for RuntimeEngine

fn default() -> Self

Returns the “default value” for a type.