Struct Composition 

pub struct Composition<A: Applier + 'static> { /* private fields */ }

A running composition that turns root content into nodes. A is the applier type that creates and edits those nodes.

Implementations

impl<A: Applier + 'static> Composition<A>

pub fn new(applier: A) -> Self

Creates a composition that builds its nodes through applier and uses a new runtime with the default scheduler.

pub fn with_runtime(applier: A, runtime: Runtime) -> Self

Creates a composition that builds its nodes through applier and uses runtime for state invalidation and scheduling.

pub fn root_key(&self) -> Option<Key>

Returns the root group key captured from the most recent render() call, or None before the first render.

pub fn set_retention_policy(&self, policy: RetentionPolicy)

Sets the budget and the eviction order for groups retained when they leave the composition. See RetentionMode.

pub fn take_root_render_request(&mut self) -> bool

Returns whether a root render was requested and clears the request.

pub fn request_root_render(&mut self)

Requests another render of the root content and schedules a frame for it.

pub fn render( &mut self, key: Key, content: impl FnMut(), ) -> Result<(), NodeError>

Composes content as the root group identified by key, then recomposes the scopes that became invalid during the pass.

pub fn render_stable( &mut self, key: Key, content: impl FnMut(), ) -> Result<(), NodeError>

Perform a root render and continue replaying any resulting root-render requests until the composition reaches a stable fixpoint.

pub fn reconcile( &mut self, key: Key, content: impl FnMut(), ) -> Result<bool, NodeError>

Process invalid scopes and any resulting root-render requests until the composition reaches a stable fixpoint for the supplied root content.

pub fn should_render(&self) -> bool

Returns true if composition needs to process invalid scopes (recompose).

This checks both:

• has_updates(): composition scopes that were invalidated by state changes
• needs_frame(): animation callbacks that may have pending work

Note: For scroll performance, ensure scroll state changes use Cell<T> instead of MutableState<T> to avoid triggering recomposition on every scroll frame.

pub fn should_recompose(&self) -> bool

Whether any composition scope is actually invalid, i.e. whether running the composable tree could produce a different result than last time.

Deliberately excludes Runtime::needs_frame, which Self::should_render includes. An armed frame callback means the runtime owes someone a tick - a future to resume, a dispatcher to drain - and every app with a game loop or a polling effect has one armed at all times. Re-running the composition for it recomposes a tree that nothing invalidated. Callers deciding “should I tick” want Self::should_render; callers deciding “should I recompose” want this.

It is only meaningful after the frame callbacks have been drained: a callback that writes state invalidates its readers as it runs, so the answer is a question about work already discovered, not work still to come.

pub fn runtime_handle(&self) -> RuntimeHandle

Returns a handle to the runtime this composition uses.

pub fn applier_mut(&mut self) -> ApplierGuard<'_, A>

Borrows the applier mutably. Panics if it is already borrowed.

pub fn root(&self) -> Option<NodeId>

Returns the root node a pass produced, or None if none has yet.

pub fn debug_dump_slot_table_groups( &self, ) -> Vec<(usize, Key, Option<usize>, usize)>

Returns one (group index, call site key, scope id, subtree length) tuple per group in the slot table, for debugging.

pub fn debug_dump_slot_entries(&self) -> Vec<SlotDebugEntry>

Returns the entries of the slot table, for debugging.

pub fn slot_table_heap_bytes(&self) -> usize

Returns the heap memory in bytes that the slot table holds.

pub fn debug_slot_table_stats(&self) -> SlotTableDebugStats

Returns size counters of the slot table, for debugging.

pub fn debug_slot_snapshot(&self) -> SlotDebugSnapshot

Returns a copy of the slot table’s structure, for debugging.

pub fn debug_last_pass_stats(&self) -> CompositionPassDebugStats

Returns the buffer sizes of the last composition pass, for debugging.

pub fn process_invalid_scopes(&mut self) -> Result<bool, NodeError>

Recomposes the scopes that state changes invalidated, until none remain or a root render is requested. Returns true if a pass recomposed content.

impl<A: Applier + 'static> Composition<A>

pub fn flush_pending_node_updates(&mut self) -> Result<(), NodeError>

Applies the node updates that the runtime has queued to the applier, without recomposing.

Trait Implementations

impl<A: Applier + 'static> Drop for Composition<A>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.