Struct RuntimeHandle 

pub struct RuntimeHandle { /* private fields */ }

Handle to the embedded beamr scheduler and code-server state.

Implementations

impl RuntimeHandle

pub fn propagate_activity_outcome( &self, parent_pid: Pid, activity_pid: Pid, ) -> Result<(), EngineError>

Block until an activity exits, then surface its success or failure to the parent.

Normal returns become typed payload results queued for the workflow and abnormal exits become typed activity errors that can be read alongside the trapped EXIT message delivered by the runtime link.

Errors

Returns EngineError::Runtime when the parent is not live, the result term cannot be converted to a payload, or mailbox delivery fails.

pub fn deliver_signal_received( &self, workflow_pid: Pid, ) -> Result<(), EngineError>

Deliver a recorded signal wake marker to the workflow mailbox surface.

The marker is a pure wake: the signal payload was already durably recorded by the signal router before delivery, and the awaiting NIF resolves it from recorded history. Nothing is retained here.

Blocking variant for synchronous callers (engine-seam trait impls and scheduler-thread paths); async tasks use Self::deliver_signal_received_async so their executor threads are never parked in std::thread::sleep.

Errors

Returns EngineError::Runtime when the workflow is not live or the mailbox marker cannot be queued.

pub fn deliver_activity_result( &self, parent_pid: Pid, activity_pid: Pid, payload: Payload, ) -> Result<(), EngineError>

Deliver a successful activity result payload to the workflow mailbox surface.

Errors

Returns EngineError::Runtime when the workflow is not live or the mailbox marker cannot be queued.

pub fn deliver_activity_error( &self, parent_pid: Pid, activity_pid: Pid, error: ActivityError, ) -> Result<(), EngineError>

Store a typed activity error for a trapped activity EXIT signal.

Errors

Returns EngineError::Runtime when the workflow process is not live.

pub fn activity_result( &self, parent_pid: Pid, activity_pid: Pid, ) -> Option<Payload>

Read a previously delivered activity result payload.

pub fn activity_error( &self, parent_pid: Pid, activity_pid: Pid, ) -> Option<ActivityError>

Read a previously delivered activity error associated with a trapped exit.

pub fn retained_activity_completions(&self) -> usize

Number of retained two-phase activity completion entries (results plus failures) across every workflow process.

Diagnostic surface: after a workflow exits, the monitor drain must leave nothing behind for its pid, so an engine with no live awaits should report zero.

impl RuntimeHandle

pub fn new(config: RuntimeConfig) -> Result<Self, EngineError>

Construct and start an embedded runtime from builder-supplied config.

Errors

Returns EngineError::Runtime when beamr cannot start its scheduler.

pub fn install_nifs( &self, registration: NifRegistration, ) -> Result<(), EngineError>

Install collected NIF entries into beamr’s native registry.

Consumes the registration collection so no caller can append more entries after this installation step. Callers must invoke this before loading and spawning workflow modules whose imports depend on these NIFs.

Errors

Returns EngineError::NifRegistration when beamr rejects an entry, including duplicate module/function/arity registrations.

pub fn registered_nif_modules(&self) -> Vec<String>

Return module names that have registered NIFs and should not be content-hash renamed during package loading.

pub fn spawn_workflow( &self, deployed_module: &str, function: &str, input: RuntimeInput, ) -> Result<Pid, EngineError>

Spawn a top-level workflow process at a deployed module/function entrypoint.

Errors

Returns EngineError::Runtime when the module/function/arity cannot be resolved or beamr rejects the spawn request.

pub fn spawn_workflow_trapping( &self, deployed_module: &str, function: &str, input: RuntimeInput, ) -> Result<Pid, EngineError>

Spawn a top-level workflow process with trap-exit enabled before it runs.

Errors

Returns EngineError::Runtime when the module/function/arity cannot be resolved or beamr rejects the spawn request.

pub fn spawn_activity( &self, parent_pid: Pid, deployed_module: &str, function: &str, input: RuntimeInput, ) -> Result<Pid, EngineError>

Spawn an activity child process linked to its workflow parent.

Errors

Returns EngineError::Runtime when the parent process is not live, the module/function/arity cannot be resolved, or beamr rejects the linked spawn request.

pub fn is_dirty(&self, module: &str, function: &str) -> bool

Return whether the registered native activity entry is dirty for arity 1.

pub fn is_dirty_with_arity( &self, module: &str, function: &str, arity: u8, ) -> bool

Return whether the registered native entry is dirty for the supplied arity.

pub fn cancel_pid(&self, pid: Pid) -> Result<(), EngineError>

Cancel a live process by PID.

Errors

Returns EngineError::Runtime when pid is not live.

pub fn set_trap_exit(&self, pid: Pid, value: bool) -> Result<bool, EngineError>

Set a live process’ trap-exit flag, returning the previous value.

Errors

Returns EngineError::Runtime when pid is not live.

pub fn is_live(&self, pid: Pid) -> bool

Return true when pid is currently live.

pub fn trap_exit(&self, pid: Pid) -> Result<bool, EngineError>

Return a live process’ trap-exit flag.

Errors

Returns EngineError::Runtime when pid is not live.

pub fn is_linked(&self, left: Pid, right: Pid) -> Result<bool, EngineError>

Return true when two live processes have a bidirectional link.

Errors

Returns EngineError::Runtime when either process is not live.

pub fn shutdown(&self) -> Result<(), EngineError>

Shut down the embedded scheduler and wait for worker threads to stop.

Errors

Currently infallible; reserved for typed runtime shutdown failures.

impl RuntimeHandle

pub fn register_module( &self, deployed_name: &str, beam_bytes: &[u8], ) -> Result<(), EngineError>

Register transformed BEAM bytes under their already-deployed module name.

Only rewrites self-references. Use Self::register_module_with_renames for package loads where cross-module imports need the full rename map.

Errors

Returns EngineError::Runtime when beamr cannot prepare the module bytes or when the deployed name still has retained old code in the registry.

pub fn register_module_with_renames( &self, deployed_name: &str, beam_bytes: &[u8], rename_map: &ModuleRenameMap, ) -> Result<(), EngineError>

Register BEAM bytes with a full package rename map for cross-module import rewriting.

Errors

Returns EngineError::Runtime when beamr cannot prepare the module bytes or when the deployed name still has retained old code in the registry.

pub fn package_rename_map( &self, original_names: &[&str], deployed_names: &[&str], ) -> ModuleRenameMap

Build the atom-level rename map for every module in a package.

pub fn has_registered_module(&self, deployed_name: &str) -> bool

Return true when a module has been registered in the embedded module registry.

pub fn module_exports_function( &self, deployed_name: &str, function: &str, ) -> bool

Return true when a registered module exports function at any arity.

Workflow entry points are spawned at arity 0 or 1 depending on input; the load-time route commit only needs to know the name is exported at all — a wrong-arity spawn still fails typed at dispatch.

impl RuntimeHandle

pub fn monitor_process<F>( self: &Arc<Self>, pid: Pid, callback: F, ) -> Result<ProcessMonitorHandle, EngineError>

where F: FnOnce(Result<WorkflowProcessOutcome, EngineError>) + Send + 'static,

Install a runtime-owned monitor that invokes callback when pid exits.

The callback runs on a dedicated monitor thread outside workflow dirty NIF execution. The runtime boundary owns the process wait and BEAM term conversion so lifecycle code never imports beamr types.

Errors

Returns EngineError::Runtime when pid is neither live nor a process this runtime previously spawned. A monitored process that already exited is accepted: its outcome is still observable through the scheduler’s exit tombstone, so the callback fires immediately instead of the spawn path spuriously failing for fast-completing workflows.

impl RuntimeHandle

pub fn workflow_outcome( &self, pid: Pid, ) -> Result<Result<Payload, WorkflowError>, EngineError>

Block until a workflow exits and convert its terminal runtime outcome.

Normal returns become durable result payloads. Abnormal exits become typed workflow errors so lifecycle code can record a terminal failure.

Errors

Returns EngineError::Runtime when the result term cannot be converted into a payload.