Struct RuntimeError 

pub struct RuntimeError {
    pub message: String,
    pub span: Option<Span>,
    pub rule: Option<Box<str>>,
    pub help: Option<Box<str>>,
    pub outcome: RunOutcome,
    pub denied_capability: Option<Box<str>>,
    /* private fields */
}

Fields

message: String

span: Option<Span>

rule: Option<Box<str>>

Box<str> rather than String, here and for help and denied_capability, because none of the three is ever grown after it is set and a String’s capacity word is eight bytes this type pays on every Result that can carry it — of which there are some three hundred and sixty signatures. The three together are twenty-four bytes, which is the difference between tripping clippy::result_large_err and clearing it with room.

help: Option<Box<str>>

outcome: RunOutcome

Which of the three this error is, for the terminal trace event of a run that ends with it.

The default is RunOutcome::Invariant, because that is what most of them are and because it is the honest answer for an error raised by code that knows nothing about limits or boundaries. The two parties that do know say so: crate::budget::Budget names the limit it stopped the run for, and crate::host::HostRegistry names the Host API boundary when it is the boundary that refused. It is never RunOutcome::Success or RunOutcome::Error, which are what a run that did not fail reports.

denied_capability: Option<Box<str>>

The capability the Host API boundary refused this call for, when a capability was the reason.

RunOutcome::HostBoundary is set for everything the boundary rejects — an unknown module, an operation that does not exist, an argument or result the schema does not admit, an exhausted budget — so it cannot answer whether this particular run was simply not granted enough. This field can: only the grant check in crate::host::HostRegistry sets it, and only with the capability it refused.

Implementations

impl RuntimeError

pub fn new(message: impl Into<String>) -> Self

pub fn at(self, span: Span) -> Self

pub fn chain(&self) -> &[Span]

The call-site spans of the calls that were live when this was raised, innermost first, bounded to MAX_CALL_CHAIN entries by RuntimeError::with_chain.

pub fn chain_omitted(&self) -> usize

How many call-site spans past MAX_CALL_CHAIN were dropped to keep RuntimeError::chain bounded.

pub fn with_chain(self, sites: impl IntoIterator<Item = Span>) -> Self

Attaches sites as the call chain, innermost first, keeping the innermost MAX_CALL_CHAIN and recording how many more were dropped.

A no-op once a chain is attached. The VM and the interpreter each have exactly one place that calls this — where the error leaves the machine, and inside call_target for every level of the interpreter’s own recursion — and the second of those runs once per frame the error unwinds through. The guard is what makes that safe: the first frame to see the error attaches the whole chain it can still see, and every frame further out finds one already there and leaves it alone, rather than overwriting it with the shorter chain its own, later vantage point would otherwise compute.

pub fn with_rule(self, rule: impl Into<Box<str>>) -> Self

pub fn with_help(self, help: impl Into<Box<str>>) -> Self

pub fn with_outcome(self, outcome: RunOutcome) -> Self

Classifies this error as outcome for the terminal trace event.

A classification set once is kept: the innermost party to a failure is the one that knows what it was, and an error travelling outward through a host call or a callback must not be relabelled by whatever it passes through on the way.

pub fn with_denied_capability(self, capability: impl Into<Box<str>>) -> Self

Records capability as the one the Host API boundary refused this call for.

Call this only from the grant check itself: it is what lets a caller tell “this run was simply not granted enough” apart from the rest of what RunOutcome::HostBoundary covers.

pub fn to_diagnostic(&self) -> Diagnostic

Trait Implementations

impl Clone for RuntimeError

fn clone(&self) -> RuntimeError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RuntimeError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.