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.
Retained cross-plan replacement: move an adopted [RetainedInstance] from
its compiled Plan to a newly compiled one while keeping the Scene nodes of
every visual whose authored key and kind are still compatible.
The stable key is the caller's [NodeKey] (authored node key or
asset-expansion key) carried by each [VisualSpec]. Per key, in one Scene
edit: same key, same ModelKey and same content family retain the existing
NodeId; keys absent from the new specs are retired (their nodes removed);
new keys are inserted; a key whose model key or content family changed is
retired and re-created, so a stale NodeId can never alias a different
kind of node. Sibling order follows the new spec order, so pixels equal a
cold rebuild of the new plan.
The new runtime is built and evaluated on the side. The old runtime, Scene
contents, visual table and epoch are replaced only after the single Scene
commit succeeds; any earlier failure (compile-shaped refusal, evaluation,
fit, capacity, or the caller's update hook) leaves the previous adoption
exactly as it was. No painter, router or layout solver is created.
Structs
structaster_blueprint::retarget::NodeEndpoint
pub struct NodeEndpoint { /* see fields */ }Authority-free handle to one retained visual at one adopted plan epoch. Not a capability: it only lets a caller detect that its binding went stale.
Methods
fn key(&self) -> NodeKeyfn node(&self) -> NodeId
Trait implementations: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq
structaster_blueprint::retarget::PreparedRetarget
pub struct PreparedRetarget { /* see fields */ }Everything fallible and Scene-free about one retarget, already done: specs
resolved, the new runtime built and evaluated, node descriptions validated
against the device and command budget, capacity checked. Produced by
[RetainedInstance::prepare_retarget] (which only borrows the instance
immutably); consumed by [PreparedRetarget::commit].
Dropping it has no effect on any instance. It is bound to the instance
serial and epoch it was prepared against and is refused (StalePrepared)
anywhere else, including after a different retarget was adopted.
Methods
fn plan(&self) -> &Arc<Plan>fn retiring(&self) -> &[(NodeKey, NodeId)]— Keys whose node would be removed.fn commit(self, instance: &mut RetainedInstance) -> Result<RetargetReport, RetargetError>— Apply toinstance. Seecommit_with.fn commit_with<R>(self, instance: &mut RetainedInstance, update: impl FnOnce(&Candidate, &mut Edit<'_>) -> Result<R, Error>) -> Result<(RetargetReport, R), RetargetError>— The single Scene commit plus adoption. This is the only remaining fallible step: the Scene transaction (andupdate) can still refuse, for example when caller-attached controls leave too little node room. A Scene transaction cannot be prepared separately, so it is not infallible; onErrthe Scene, runtime, visual table and epoch are exactly as before (the failed Edit aborts). After the Scene commit succeeds the adoption is plain moves and field assignments: the next epoch was checked in prepare, and the new visual table and the retained/added lists are built (and sized) inside the Scene edit, before its finalcommit, where a failure still aborts everything.fn commit_for_renderer(self, instance: &mut RetainedInstance, renderer: &mut Renderer) -> Result<RetargetReport, RetargetError>— Ascommit, but the single Scene edit is admitted againstrendererwithEdit::commit_for_renderer. A refusal (for example a finite but enormous Recording) aborts exactly like any other Scene refusal: nodes, runtime, visual table and epoch are unchanged. Directrender_sceneonly; PreparedScene affine/group composition is not covered.fn commit_with_for_renderer<R>(self, instance: &mut RetainedInstance, renderer: &mut Renderer, update: impl FnOnce(&Candidate, &mut Edit<'_>) -> Result<R, Error>) -> Result<(RetargetReport, R), RetargetError>—commit_withplus renderer admission.
structaster_blueprint::retarget::RetargetReport
pub struct RetargetReport { /* see fields */ }What one adopted retarget did. Only produced after success.
Public fields
| field | type | |
|---|---|---|
retained | Vec<(model::NodeKey, aster_ui::NodeId)> | Keys whose existing NodeId survived. |
retired | Vec<(model::NodeKey, aster_ui::NodeId)> | Keys whose old node was removed (including replaced kinds). |
added | Vec<(model::NodeKey, aster_ui::NodeId)> | Keys given a fresh node (including replaced kinds). |
stamp | aster_ui::SceneStamp |
Methods
fn from_plan(&self) -> PlanIdfn to_plan(&self) -> PlanIdfn remap(&self, endpoint: &NodeEndpoint) -> Result<NodeEndpoint, StaleEndpoint>— Carry an endpoint taken before this retarget over to the new plan. Refuses endpoints older than the replaced adoption and removed nodes.fn rebind_event(&self, old: &OwnedEndpoint, new_plan: &Arc<Plan>) -> Result<OwnedEndpoint, EndpointError>— Re-select an event/intent endpoint on the new plan. The old endpoint must belong to the replaced plan and the same output name must still exist on the new plan with the same declared type.
Trait implementations: Clone, Debug
Enums
enumaster_blueprint::retarget::RetargetError
pub enum RetargetError { SamePlan, CapacityExceeded, StalePrepared, EpochExhausted, Retained }Variants
SamePlan— The target is the plan already adopted; use evaluate/commit instead.CapacityExceeded— The new plan needs more visual nodes than the Scene's fixed capacity. Nothing was changed. Node ids cannot be kept across a larger Scene; the caller may choose [RetainedInstance::cold_rebuild] (or [edit_and_rebuild_cold]) and accept brand-new ids.StalePrepared— A [PreparedRetarget] was committed to an instance that is not the one (or not the adoption state) it was prepared against.EpochExhausted— The adoption epoch is atu64::MAX, so another retarget cannot be numbered. Refused in prepare; nothing was changed. The caller may resynchronise with [RetainedInstance::cold_rebuild], which restarts the epoch at 0.Retained
Trait implementations: Debug, Display, Error, From<E>
enumaster_blueprint::retarget::StaleEndpoint
pub enum StaleEndpoint { Generation, Removed }Why a node endpoint can no longer be used.
Variants
Generation— Taken from another plan or before the latest adopted retarget.Removed— The keyed node was retired (or replaced by a different node).
Trait implementations: Clone, Copy, Debug, Display, Eq, Error, PartialEq, StructuralPartialEq
enumaster_blueprint::retarget::StepRetargetError
pub enum StepRetargetError { Editor, Allocation, Retarget }Failure of an undo/redo that also retargets. In every case the editor (Arcs, revision, history) and the Scene are exactly as before the call.
Variants
Editor— The editor refused the step (nothing to undo/redo, revision exhausted).Allocation— The editor's history reserve failed before the retarget was attempted.Retarget— The retarget (or its renderer admission) was refused; nothing moved.
Trait implementations: Debug, From<ApplyWithError<RetargetError>>
Functions
fnaster_blueprint::retarget::edit_and_rebuild_cold
pub fn edit_and_rebuild_cold(editor: &mut editor::Editor, expected_revision: u64, changes: &[editor::Change], specs: impl FnOnce(&std::sync::Arc<compiler::Plan>) -> Vec<retained::VisualSpec>, limits: retained::VisualLimits, parameters: &std::collections::BTreeMap<model::Symbol, model::Literal>, resources: &dyn ResourceResolver, clock: Option<f64>, output: aster_ui::Output) -> Result<(editor::EditOutcome, retained::RetainedInstance), editor::ApplyWithError<retained::RetainedError>>The caller-chosen capacity fallback, still atomic: the editor edit is admitted only if a larger Scene could be built cold for the candidate plan. On success the returned instance replaces the old one (the caller assigns it); on failure the editor and the old instance are untouched. Node ids and endpoints of the old instance do NOT carry over.
fnaster_blueprint::retarget::edit_and_retarget
pub fn edit_and_retarget(editor: &mut editor::Editor, retained: &mut retained::RetainedInstance, expected_revision: u64, changes: &[editor::Change], specs: impl FnOnce(&std::sync::Arc<compiler::Plan>) -> Vec<retained::VisualSpec>, parameters: &std::collections::BTreeMap<model::Symbol, model::Literal>, resources: &dyn ResourceResolver, clock: Option<f64>, output: aster_ui::Output) -> Result<(editor::EditOutcome, RetargetReport), editor::ApplyWithError<RetargetError>>One topology edit, atomic end to end. The editor compiles the candidate,
then specs chooses the visuals for the candidate plan, then the retarget
is prepared and, as the very last fallible step inside the admission
callback, committed to the Scene. The editor adopts only after that
returned Ok, and its adoption is infallible. So a refusal or failure in
either step leaves the editor (Arcs, revision, history) and the Scene
(contents, SceneStamp, node ids, epoch) in their previous adopted state.
A CapacityExceeded refusal arrives as ApplyWithError::Admit. The only
residual window is the infallible assignments between the Scene commit and
returning from the callback; a panic inside the caller's specs closure
happens before the Scene commit.
fnaster_blueprint::retarget::edit_and_retarget_for_renderer
pub fn edit_and_retarget_for_renderer(editor: &mut editor::Editor, retained: &mut retained::RetainedInstance, expected_revision: u64, changes: &[editor::Change], specs: impl FnOnce(&std::sync::Arc<compiler::Plan>) -> Vec<retained::VisualSpec>, parameters: &std::collections::BTreeMap<model::Symbol, model::Literal>, resources: &dyn ResourceResolver, clock: Option<f64>, output: aster_ui::Output, renderer: &mut aster_ui::Renderer) -> Result<(editor::EditOutcome, RetargetReport), editor::ApplyWithError<RetargetError>>As [edit_and_retarget], but the Scene edit is admitted against renderer
with Edit::commit_for_renderer. A candidate the renderer would refuse (for
example a finite but enormous Recording) arrives as
ApplyWithError::Admit(RetargetError::Retained(..)) and leaves the editor
and the Scene unchanged. Direct render_scene only.
fnaster_blueprint::retarget::redo_and_retarget
pub fn redo_and_retarget(editor: &mut editor::Editor, retained: &mut retained::RetainedInstance, specs: impl FnOnce(&std::sync::Arc<compiler::Plan>) -> Vec<retained::VisualSpec>, parameters: &std::collections::BTreeMap<model::Symbol, model::Literal>, resources: &dyn ResourceResolver, clock: Option<f64>, output: aster_ui::Output) -> Result<(editor::EditOutcome, RetargetReport), StepRetargetError>As [undo_and_retarget], for Editor::redo_with.
fnaster_blueprint::retarget::redo_and_retarget_for_renderer
pub fn redo_and_retarget_for_renderer(editor: &mut editor::Editor, retained: &mut retained::RetainedInstance, specs: impl FnOnce(&std::sync::Arc<compiler::Plan>) -> Vec<retained::VisualSpec>, parameters: &std::collections::BTreeMap<model::Symbol, model::Literal>, resources: &dyn ResourceResolver, clock: Option<f64>, output: aster_ui::Output, renderer: &mut aster_ui::Renderer) -> Result<(editor::EditOutcome, RetargetReport), StepRetargetError>As [redo_and_retarget], with renderer admission of the Scene edit.
fnaster_blueprint::retarget::undo_and_retarget
pub fn undo_and_retarget(editor: &mut editor::Editor, retained: &mut retained::RetainedInstance, specs: impl FnOnce(&std::sync::Arc<compiler::Plan>) -> Vec<retained::VisualSpec>, parameters: &std::collections::BTreeMap<model::Symbol, model::Literal>, resources: &dyn ResourceResolver, clock: Option<f64>, output: aster_ui::Output) -> Result<(editor::EditOutcome, RetargetReport), StepRetargetError>Editor::undo_with whose admission callback prepares and commits the
retarget to the restored plan. Atomic like [edit_and_retarget]: a refused
retarget (including CapacityExceeded) leaves the editor (revision, Arcs,
both stacks) and the Scene unchanged; success moves both.
fnaster_blueprint::retarget::undo_and_retarget_for_renderer
pub fn undo_and_retarget_for_renderer(editor: &mut editor::Editor, retained: &mut retained::RetainedInstance, specs: impl FnOnce(&std::sync::Arc<compiler::Plan>) -> Vec<retained::VisualSpec>, parameters: &std::collections::BTreeMap<model::Symbol, model::Literal>, resources: &dyn ResourceResolver, clock: Option<f64>, output: aster_ui::Output, renderer: &mut aster_ui::Renderer) -> Result<(editor::EditOutcome, RetargetReport), StepRetargetError>As [undo_and_retarget], with renderer admission of the Scene edit.