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_outbox_completion( &self, registry: &Registry, workflow_id: &WorkflowId, activity_id: &ActivityId, run_id: Option<&RunId>, result: String, ) -> Result<bool, EngineError>

Route an unmatched durable-outbox activity completion into the live workflow’s mailbox.

Resolves workflow_id to its live pid through registry (the RuntimeHandle does not hold the registry) and delegates to Self::deliver_activity_completion_message, whose retained payload the engine’s take_and_record later records as the terminal.

Returns Ok(true) when delivered to a live workflow and Ok(false) when no run for the workflow is currently live — the expected stale-completion case after a crash or eviction, which recovery re-arms. A false is not an error: the caller logs it at debug.

Errors

Returns EngineError::RegistryPoisoned when the registry index lock was poisoned, EngineError::ActivityDeliveryPoisoned when the resolved workflow’s scoped delivery gate was poisoned, or EngineError::Runtime when the process is not live or the mailbox marker cannot be queued.

pub fn deliver_outbox_failure( &self, registry: &Registry, workflow_id: &WorkflowId, activity_id: &ActivityId, run_id: Option<&RunId>, reason: String, ) -> Result<bool, EngineError>

Route an unmatched durable-outbox activity failure into the live workflow’s mailbox.

Failure twin of Self::deliver_outbox_completion: same registry resolution and the same not-live Ok(false) outcome, delegating to Self::deliver_activity_failure_message.

Errors

Returns EngineError::RegistryPoisoned when the registry index lock was poisoned, EngineError::ActivityDeliveryPoisoned when the resolved workflow’s scoped delivery gate was poisoned, or EngineError::Runtime when the process 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::ActivityDeliveryPoisoned when the parent’s scoped delivery gate was poisoned, or 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::ActivityDeliveryPoisoned when the parent’s scoped delivery gate was poisoned, or 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. Returns EngineError::Gate3BifReplacementMissing if beamr’s complete Gate-3 table no longer contains a required tracked fun-spawn BIF.

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 spawn_activity_closure( &self, parent_pid: Pid, closure_term: Term, ) -> Result<Pid, EngineError>

Spawn an in-VM activity child process linked to its workflow parent, running a zero-arity closure (the SDK-composed runner thunk).

beamr deep-copies the closure’s environment into the child’s own heap before the child becomes runnable (Scheduler::spawn_link_closure), so no spawn heap is retained here and the caller’s heap may move (GC) the moment this returns. The child does not trap exits: workflow cancellation propagates through the link, and an abnormal child exit is observed by the in-VM completion watcher via Self::in_vm_child_outcome.

No parent readiness wait is performed: the only production caller is the dispatch NIF executing ON the parent process, which is therefore already materialized (a readiness poll on an Executing slot would be pointless at best).

Errors

Returns EngineError::Runtime when the parent is not live, the term is not a zero-arity closure, or its module cannot be resolved.

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 one completion callback against the pid’s owned exit record.

Errors

Returns a typed runtime error for unknown pids, duplicate committed installations, or an abort already owning this pid generation.

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.