Struct StreamCapture 

pub struct StreamCapture { /* private fields */ }

The graph capture of one pooled backend stream: where it sits in the lifecycle, and the memory its recorded launches were given.

The two travel together because neither is meaningful alone. A launch is remembered only while the window is recording, and what it remembers is only ever read once the window closes — so pairing them makes “buffers accumulate inside a window and nowhere else” a property of the type rather than a rule each backend has to keep.

Why the memory is worth keeping: a replay runs every recorded launch or none, so a replay that fails to enqueue leaves all of them exactly as they were, and so does a capture that never seals. Either way a later read of one has to fail rather than copy out bytes nothing wrote — which needs the list the launches themselves no longer hold, as bindings, so the failure can be tainted onto the allocations they resolve to.

Implementations

impl StreamCapture

pub fn record(&mut self, buffers: impl IntoIterator<Item = BufferBinding>)

Remember the memory a launch was given, when the stream is recording.

A no-op outside a window, where a launch that fails taints its own buffers on the spot and there is no graph to answer for them later.

pub fn take_recorded(&mut self) -> Vec<BufferBinding>

The memory of the capture that just closed, each claim named once — the same buffer comes back once per recorded launch that was given it.

Deduplicated by claim_key, because the taint bookkeeping is range-exact and this list is what gets claimed and released: two tensors carved from one batched allocation are two claims, and collapsing them to their shared memory id would leave every sibling but one unclaimed on a refusal and unreleased on a replay.

pub fn fail(&mut self, error: ServerError)

Doom the recording: work inside the window failed or was skipped — see Self::take_failure. The first failure wins, and a stream that is not recording has no window to doom.

pub fn retain_host(&mut self, bytes: Bytes)

Keep bytes alive for the graph this recording seals into: a recorded copy holds their raw pointer and re-reads them on every replay, so they must not return to any pool or allocator while the graph lives. Handed to the graph by take_retained_host.

Only meaningful while recording — outside a window the bytes belong in the drop queue, whose fence knows when the device is done with them.

pub fn take_retained_host(&mut self) -> Vec<Bytes>

The host memory the window’s recorded copies read from, taken as it closes — onto the graph when it seals, or to be dropped when it does not, since a recording that never becomes a graph never runs them.

pub fn take_failure(&mut self) -> Option<ServerError>

The failure that doomed this window, taken as it closes. Some means the recording is missing at least one operation and must not seal.

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 the capture, and during which a neighbour sharing the pooled stream is refused.

pub fn is_active(&self) -> bool

Whether a capture is prepared or recording — the span over which the pooled stream is committed to one logical stream’s window.

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

The logical stream that opened the window, while one is open. None outside a capture, which is what distinguishes a neighbour’s operation from the owner’s.

pub fn cache_mode(&self) -> CacheMode

How the metadata caches behave for this stream right now: a window pins what it builds, so a replay finds the same entries it recorded against.

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

Arm the persistent pools for the warmup run; begin may open the window afterwards. A capture starts from an empty recording, so a window that was abandoned mid-flight cannot leak its buffers into the next one.

Errors

Fails when a capture is already prepared or recording, leaving both the state and the recording untouched.

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

Open the window: launches from here until end are recorded rather than executed.

Errors

Fails when no capture is prepared, or one is already recording.

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

Close the window, saying whether caller owned it — see CaptureEnd. The recording survives the transition for take_recorded to collect.

Errors

Fails when no capture is recording, leaving the state untouched.

pub fn abort(&mut self)

Give up a prepared capture that never opened, restoring the stream to no-capture. Whatever it had recorded or retained goes with it.

Trait Implementations

impl Debug for StreamCapture

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

Formats the value using the given formatter.

impl Default for StreamCapture

fn default() -> Self

Returns the “default value” for a type.