Struct StreamCaptureState 

pub struct StreamCaptureState { /* private fields */ }

Where a stream sits in the graph-capture lifecycle, and the only thing allowed to move it. Capture is a strict NoCapture → Prepare → Capture → NoCapture progression, driven by prepare, begin and end; each rejects an out-of-order call, so a capture can never start unprepared and two captures can never overlap on one stream.

One capture, one logical stream

The three calls have to come from the same logical stream. The window is opened on the pooled stream that logical stream folds onto, and the launches in between are recorded there — so a caller whose StreamId changes half-way (an .await resuming on another thread under the default PerThread policy, without set_stream pinning) has already split its recording across two backend streams before it ever reaches end. Pin the stream around a capture; end treats a caller that is not the owner as a window nobody is coming back for, and abandons it.

The transitions live here rather than in each backend server because the rule is the same on every one of them — a backend supplies only the work a transition brackets (arming its pools, opening the driver’s capture), never the ordering rule itself.

What the neighbours pay

The window is held on a pooled stream, and logical streams fold onto those with id % max_streams — so a capture costs every logical stream sharing that slot, not just the one recording. On a software-graph backend a neighbour’s read, sync or profile is refused outright for the duration, and its write is refused with the refusal landing on its own destinations; on a hardware-graph backend a neighbour’s fenced flush is deferred until the window closes. None of that is attributed to the capture, because a refusal is not a failure of the capture: the neighbour asked for something this slot cannot do right now.

It is a real cost of folding, and the reason a capture is worth pinning to a stream nothing else is scheduled on.

Both active states carry the logical stream that opened the capture. Several logical streams share one backend stream, so “the capture owns this stream for its window” only holds if the window remembers whose it is: an error raised inside it dooms the capture, not whichever neighbour happens to be using the slot.

Implementations

impl StreamCaptureState

pub fn is_recording(&self) -> bool

Whether launches on the stream are being recorded into a graph right now — the window during which a host sync would abort (or is rejected by) the capture.

pub fn is_preparing(&self) -> bool

Whether the warmup run is under way: prepared, and the window not open yet.

pub fn is_active(&self) -> bool

Whether a capture is prepared or recording — the whole window during which the stream is not free to serve other work.

pub fn owner(&self) -> Option<StreamId>

The logical stream this capture belongs to, None outside a window.

pub fn device(&self) -> &CaptureStatus

The captures of the whole device this stream belongs to, this one included.

pub fn prepare(&mut self, owner: StreamId) -> Result<(), ServerError>

NoCapture → Prepare, for graph_prepare. Call before arming the pools; the caller owns the arming, this owns the rule that it happens exactly once per capture.

Errors

Fails when a capture is already prepared or already recording on this stream, leaving the state untouched — two captures may never overlap on one stream. The caller can retry after end_capture.

pub fn begin(&mut self) -> Result<(), ServerError>

Prepare → Capture, for begin_capture. Call before the work that opens the window (ending the priming phase, starting the driver’s capture) so a rejected call cannot run any of it: on a stream that is already recording, a drop-queue flush issued on the way to the rejection would abort the live capture.

Since the state moves before that work, a backend whose window fails to open must undo it with abort.

Errors

Fails when prepare has not run — the pools have to be warmed by a warmup run first — or when a capture is already recording. The state is left untouched.

pub fn end(&mut self, caller: StreamId) -> Result<CaptureEnd, ServerError>

Capture → NoCapture, for end_capture. Call before closing the window, so the stream leaves capture state even if sealing the graph then fails — a backend that returned an error with the state still set would wedge the stream in capture mode forever.

A caller that does not own the window closes it all the same, as CaptureEnd::Abandoned: only the owner may seal a capture, but leaving the window open until an owner that may never come back closes it would wedge the pooled stream for every logical stream sharing it — see CaptureEnd for why that is the lesser of the two.

Errors

Fails when no capture is recording (nothing prepared or started, or the capture already ended), leaving the state untouched — a stray end_capture must not close a window that was never opened.

pub fn abort(&mut self)

Return to NoCapture from anywhere, for the failure path of a transition’s own work: the window never opened, so the stream must be left fully usable and re-capturable rather than stuck preparing forever. Unlike end this asserts nothing, because the state it is recovering from is precisely the one that could not be completed.

Trait Implementations

impl Debug for StreamCaptureState

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

Formats the value using the given formatter.

impl Drop for StreamCaptureState

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.