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 new(device: &DeviceCaptures) -> Self

The capture of one more stream of the device whose captures device records.

pub fn device(&self) -> &CaptureStatus

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

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 touch(&mut self, stream: StreamId, location: MemoryLocation)

Remember that a launch was given the memory at location, owned by stream, when the stream is recording: the graph replays against that page, so it has to stay where it is for the graph’s life.

pub fn take_touched(&mut self) -> Vec<TouchedPage>

The pages the recording touched, each named once, taken as the window closes. A launch touches its pages again on every recorded launch, so the list is deduplicated here, once, rather than on every touch.

pub fn page_update(&self) -> PageUpdate

What this stream’s reservations may do to the pages held.

A recording stream allocates nothing: an allocation would become part of the recording. While any stream of the device records, no page is released or renumbered, so the pages a recording touched are still the ones it guards when it seals.

pub fn prime(&mut self, staging: &ManagedMemoryBinding)

Hold staging until the window opens, when the stream is preparing a capture: a recorded copy keeps its staging for the graph’s life, so the recorded run needs a slice per copy where the warmup run could reuse one, and holding them grows the pool before nothing may be allocated.

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.

A buffer whose memory is gone by then is left out: nothing will read it again.

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

The CacheMode the metadata info cache should run in at this lifecycle position: a window pins what it builds, so a replay finds the same entries it recorded against. Both while a graph is being prepared (warmup, which primes the cache) and while it is being recorded the cache runs in CacheMode::Capture — caching every buffer and invalidating none — so the capture window finds every info buffer warm and drops none out from under a recorded launch. Normal operation uses CacheMode::Normal.

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

Start 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.

The staging the warmup run primed goes back to the pool, for the recorded run to reuse.

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.