Struct TeeHandle 

pub struct TeeHandle { /* private fields */ }

A cheaply-cloneable handle for adding or removing a Tee’s sinks while the pipeline is running. It deliberately keeps only a Weak reference to the Tee’s shared state: retaining a handle after the pipeline finishes must not keep downstream sinks or the pipeline’s crate::bus::Bus sender alive. Once the Tee is gone, TeeHandle::branch returns None.

Implementations

impl TeeHandle

pub fn branch(&self) -> Option<ChainBuilder>

A crate::pipeline::ChainBuilder pre-wired with this Tee’s own Context — lets a caller build a whole new branch (.pipe(...) chains, ending in .to(...)) at any point after the pipeline started running, then hand the result to TeeHandle::attach, without needing to retain the pipeline context separately around separately. Returns None once the Tee has been dropped.

pub fn attach(&self, branch: DetachedBranch) -> Result<BranchId>

Attaches a runtime branch, returning the stable ID used to remove it. Fixed initial branches belong in TeeBuilder. During a lifecycle or seek operation this returns GraphError::TimelineOperationInProgress immediately; build a fresh detached branch and retry after the operation finishes.

pub fn detach(&self, branch_id: BranchId) -> Result<()>

Detaches exactly the branch returned by TeeHandle::attach. The runtime peer and every graph node owned by it disappear in the same transaction. Names are deliberately not used as graph keys.

This abandons whatever the branch still held: no EOS is sent, so a stateful codec does not flush and a muxer does not finalize. That is what makes it the right call for a branch that is failing or wedged — see TeeHandle::finish_branch for ending one that is working.

pub fn finish_branch(&self, branch_id: BranchId) -> Result<()>

Ends one branch the way a recording ends: sends it an ordered Eos behind everything already queued for it, so stateful codecs flush their delayed output and a muxer writes its trailer, and detaches it.

Returns as soon as the Eos is on its way. Draining it — which means an encoder flush, a container’s trailer, and joining the branch’s own Queue workers — happens on a thread this Tee owns and joins, so a caller on a UI thread neither blocks nor has anything left to remember: branch_id is already invalid when this returns, exactly as after TeeHandle::detach. Watch the bus for the terminal’s BusEvent::Eos to learn when the branch’s output is actually complete — a file is only finished then, not when this call returns.

Siblings are untouched: the Eos goes into this branch’s pad alone, unlike one arriving at the Tee itself, which every branch sees.

The ordering guarantee is against what this Tee has already handed the branch — everything queued for it arrives before the Eos. It is not against buffers still upstream: anything the Tee has not consumed yet when this is called belongs to the stream after the stop point and never reaches this branch. There is no ordering between the two except the one the caller creates by waiting for what it wants included.

pub fn detach_branch_containing(&self, element: ElementId) -> Result<()>

Resolves the owning branch from any element ID inside it and detaches that branch. Useful when an error is attributed to a stage behind a queue rather than to the branch root.

pub fn sink_count(&self) -> usize

Returns the number of currently attached output branches.

Returns zero after the tee element has been dropped.

Trait Implementations

impl Clone for TeeHandle

fn clone(&self) -> TeeHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.