API reference

aster_blueprint::runtime

Pre-1.0: signatures are not frozen. Generated from rustdoc JSON of the compiled crate; rustdoc JSON format version 60. Only public items are listed.

Incremental slot-plane runtime evaluator over an immutable compiled Plan.

This is an intermediate data evaluator, not a retained scene, renderer, router, or native integration. It executes only the small set of builtin kernels whose names/ports are defined by the experimental builtin catalog, and it refuses anything it cannot actually compute. It never fabricates output.

Identity rules (deliberately narrow, local to a process):

  • A [RuntimeInstance] binds exactly one Arc<Plan> and has its own serial.
  • Kernels are resolved from Symbol names ONCE in [RuntimeInstance::new] into the [Kernel] enum; the hot evaluation loop never dispatches on String.
  • A [Candidate] is privately bound to the exact instance serial, PlanId and generation it was staged from. It is not Clone or Copy.
  • [RuntimeInstance::commit] re-validates that binding, runs a caller-owned fallible callback while holding &mut self, and only then adopts the candidate cache. There is no fallible work after the callback succeeds.

Structs

structaster_blueprint::runtime::Candidate

pub struct Candidate { /* see fields */ }

A staged, not-yet-adopted evaluation result. Privately bound to the exact instance serial, plan identity and generation it was produced from. This binding is what lets [RuntimeInstance::commit] refuse stale or cross-instance candidates. Deliberately not Clone/Copy.

Methods

  • fn plan_id(&self) -> PlanId
  • fn instance_serial(&self) -> u64
  • fn generation(&self) -> u64
  • fn evaluated(&self) -> usize — Instruction bodies executed to produce this candidate.
  • fn outputs(&self) -> &[(Symbol, Literal)] — Literal-valued outputs in their declared relative order. Prepared values are available through prepared_output, never fabricated as literals.
  • fn output(&self, name: &Symbol) -> Option<&Literal>
  • fn value_at(&self, slot: Slot) -> Option<&Literal>
  • fn prepared_output(&self, name: &Symbol) -> Option<&RuntimeValue>
  • fn prepared_value_at(&self, slot: Slot) -> Option<&RuntimeValue>

Trait implementations: Debug

structaster_blueprint::runtime::NoResources

pub struct NoResources;

Default resolver: every resource is absent.

Trait implementations: Clone, Copy, Debug, Default, ResourceResolver

structaster_blueprint::runtime::RuntimeInstance

pub struct RuntimeInstance { /* see fields */ }

A live evaluation instance for exactly one compiled plan. Not Clone: its serial identity and generation are the basis for candidate validity.

Methods

  • fn new(plan: Arc<Plan>) -> Result<Self, RuntimeError> — Resolves the whole plan up front: every data-domain instruction must map to a supported builtin with an exact signature, and every resource must have a literal or supported prepared type. Unknown or unsupported kernels refuse here, never producing fabricated output at evaluation time.
  • fn plan(&self) -> &Arc<Plan>
  • fn plan_id(&self) -> PlanId
  • fn serial(&self) -> u64
  • fn generation(&self) -> u64
  • fn slot_count(&self) -> usize
  • fn last_evaluated(&self) -> usize — Number of instruction bodies executed during the last committed evaluation.
  • fn resolved_kernel(&self, index: usize) -> Option<Kernel>
  • fn slot_value(&self, slot: Slot) -> Option<&Literal>
  • fn prepared_slot_value(&self, slot: Slot) -> Option<&RuntimeValue>
  • fn evaluate(&mut self, parameters: &BTreeMap<Symbol, Literal>, resources: &dyn ResourceResolver, clock: Option<f64>) -> Result<Candidate, RuntimeError> — Stages an evaluation without mutating committed state. On any refusal the instance is untouched; the returned candidate must be adopted via [Self::commit] or dropped.
  • fn commit<R, E>(&mut self, candidate: Candidate, callback: impl FnOnce(&Candidate) -> Result<R, E>) -> Result<R, CommitFailure<E>> — Transactional adoption. Order is fixed and strictly enforced: 1. exact instance serial + plan id + current generation, else Stale (the callback is NOT run); 2. generation + 1 capacity, else Capacity (callback NOT run); 3. run the caller's fallible callback while holding &mut self; 4. on Err, return Callback with the runtime untouched; 5. on Ok, adopt the candidate cache and advance the generation using only infallible work, so a failed scene commit cannot advance the cache.

Trait implementations: Debug

Enums

enumaster_blueprint::runtime::CommitFailure

pub enum CommitFailure<E> { Stale, Capacity, Callback }

Outcome of [RuntimeInstance::commit]. Callback(E) means the caller's own transaction failed; the runtime is unchanged in every non-Ok case.

Variants

  • Stale — Candidate was not staged from this instance/plan/current generation.
  • Capacity — The generation counter cannot advance; runtime unchanged.
  • Callback — Caller callback failed; runtime unchanged.

Trait implementations: Clone, Debug, Display, Eq, From<CommitFailure<MaterialInstanceError>>, PartialEq, StructuralPartialEq

enumaster_blueprint::runtime::Kernel

pub enum Kernel { Identity, Add, Multiply, Clamp, ColorMix, LengthAdd, LengthScale, LengthMax, LabelWidth, LabelHeight, Rect, RoundedRect, LabelBounds, LinearPaint, Effect, Noise, Fluid, Fx, Clock, PreparedIdentity, Select, NotExecuted }

The experimental builtin kernels. Resolution happens once per instance.

Variants

  • Identity
  • Add
  • Multiply
  • Clamp
  • ColorMix
  • LengthAdd — a + b over two LogicalLengths; negative results are allowed and a non-finite sum is refused like every other kernel output.
  • LengthScale — length * factor (Scalar factor) yielding a LogicalLength.
  • LengthMax — max(a, b) over two LogicalLengths.
  • LabelWidth — A prepared Label's measured advance / line height as a LogicalLength.
  • LabelHeight
  • Rect
  • RoundedRect — Builds one existing Recorder.fill command from validated lengths and an existing paint, and carries the resulting recording as a Drawing.
  • LabelBounds — Copies an existing measured label's advance/height into a fresh LogicalRect(x, y, advance, height). It reads the already-measured label; it never shapes, rasterizes, resizes or re-measures it.
  • LinearPaint — Builds one existing Paint::Linear from two validated sRGB8 stops and one axis flag. It creates no gradient resource, effect, shader or renderer: the flag selects only the existing horizontal/vertical axis.
  • Effect — An effect kernel (core.drawing.* shapes/strokes, core.effect.*): builds one existing vector or effect command into a Drawing.
  • Noise — A core.noise.*.v1 sampler (Scalar) or surface (Drawing); see [crate::noise_nodes].
  • Fluid — A core.fluid.*.v1 node (the sim keeps its state in its own slot, see fluid_nodes).
  • Fx — An immersive kernel (core.drawing.particles.v1, gradients, vignette, spotlight).
  • Clock
  • PreparedIdentity
  • Select — Typed eager selection. Both inputs are admitted; prepared payloads keep their original shared objects and metadata.
  • NotExecuted — An event/command-domain instruction is deliberately not executed by the pure data evaluator. It requires an actual event or explicit command dispatch, never an automatic frame tick.

Trait implementations: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

enumaster_blueprint::runtime::RuntimeError

pub enum RuntimeError { UnsupportedKernel, KernelSignature, UnknownParameter, MissingParameter, ParameterTypeMismatch, InvalidParameterValue, ResourceUnavailable, ResourceTypeMismatch, ResourceKindUnsupported, ClockUnavailable, NonDataDependency, MalformedPlan, OutputTypeMismatch, NonFiniteOutput, Preparation }

Variants

  • UnsupportedKernel
  • KernelSignature
  • UnknownParameter
  • MissingParameter
  • ParameterTypeMismatch
  • InvalidParameterValue
  • ResourceUnavailable
  • ResourceTypeMismatch
  • ResourceKindUnsupported
  • ClockUnavailable
  • NonDataDependency
  • MalformedPlan
  • OutputTypeMismatch
  • NonFiniteOutput
  • Preparation — A shape kernel refused caller data through an existing aster-ui constructor (invalid geometry, capacity, identity exhaustion). The source is the exact typed facility error; nothing is fabricated.

Trait implementations: Clone, Debug, Display, Eq, Error, From<RuntimeError>, PartialEq, StructuralPartialEq

Traits

traitaster_blueprint::runtime::ResourceResolver

pub trait ResourceResolver

Supplies typed host resources to evaluation. Absence is None, never a fabricated value; until a real adapter exists, unsupported kinds are refused.

Required and provided methods

  • fn resolve(&self, name: &Symbol, value_type: ValueType) -> Option<Literal>
  • fn resolve_prepared(&self, name: &Symbol, value_type: ValueType) -> Option<RuntimeValue>