pub struct SampleCursor { /* private fields */ }Expand description
See this module’s doc comment. Every method takes &self, so one instance can be
shared (by reference inside a thread::scope, or behind an Arc) across every
lane’s own thread.
Implementations§
Source§impl SampleCursor
impl SampleCursor
Sourcepub const fn new(start: u32, end: u32) -> Self
pub const fn new(start: u32, end: u32) -> Self
Builds a cursor over [start, end). For an export, start is wherever a prior
sequential phase (remote/hybrid calibration) left samples_done and end is
the export’s total samples_per_pixel; for a live epoch it is [0, target_samples); for a coordinator job it is the request’s
[first_sample, first_sample + samples).
Sourcepub fn claim(&self, want: u32) -> Option<(u32, u32)>
pub fn claim(&self, want: u32) -> Option<(u32, u32)>
Claims up to want fresh samples for ANY engine, returning Some((start, count)) with 1 <= count <= want, or None if the budget is already
exhausted. Never returns a range past end, however large want is.
want == 0 always returns None rather than a zero-length range.
§Why fetch_add alone is enough
One atomic read-modify-write, unconditionally advancing next by want and
then checking whether the range it was handed starts past end. fetch_add is
inherently exclusive, so every call receives a DISTINCT start with no CAS
retry loop needed. next can end up advanced PAST end (the last claim before
exhaustion typically requests more than remains) – harmless, since the
returned count is clamped to end - start and every later claim sees
start >= end and reports None. saturating is not needed in practice
(budgets are far below u32::MAX), but fetch_add wraps, so a budget near
u32::MAX must not be used.
Sourcepub fn claim_local(&self, want: u32) -> Option<(u32, u32)>
pub fn claim_local(&self, want: u32) -> Option<(u32, u32)>
Claims for the LOCAL lane only: a previously remote-failed range first (WHOLE,
however long it is), falling back to claim once that retry
pile is empty. See this module’s doc comment for why a retried range never goes
back to remote. The export’s local lane batches whatever it gets; the live
viewport uses claim_local_bounded instead.
Sourcepub fn claim_local_bounded(&self, want: u32) -> Option<(u32, u32)>
pub fn claim_local_bounded(&self, want: u32) -> Option<(u32, u32)>
Like claim_local, but never hands out more than want
samples even from the retry pile: a longer retried range is split, its head
returned now and its tail pushed back to the FRONT of the pile for the next
call. The live viewport traces one short frame per claim, so a whole failed
remote chunk (possibly hundreds of samples) must not land in a single frame.
want == 0 returns None without touching anything.
Sourcepub fn claim_any(&self, want: u32) -> Option<(u32, u32)>
pub fn claim_any(&self, want: u32) -> Option<(u32, u32)>
Claims for a crate::LanePool lane: up to want samples of a requeued range
first (split like claim_local_bounded), falling
back to fresh work from claim. Never touches the local-only
retry pile. want == 0 returns None without touching anything.
Whether the SHARED pool has nothing left to claim – true once every sample up
to end has been handed out to some engine. Says nothing about the retry
piles. A cheap, lock-free read for callers deciding whether waiting around could
still yield work.
Sourcepub fn fully_claimed(&self) -> bool
pub fn fully_claimed(&self) -> bool
Whether nothing at all is claimable right now: the shared pool is exhausted and
both retry piles are empty. A range currently being traced may still come back
through requeue or return_to_local
if its lane fails.
Sourcepub fn return_to_local(&self, start: u32, count: u32)
pub fn return_to_local(&self, start: u32, count: u32)
Returns [start, start + count) to the queue for GUARANTEED local processing
after a remote chunk failed to finish it – never re-offered to remote. A count
of 0 is a no-op (nothing to retry) rather than an empty queue entry.