pub struct PendingDropQueue<E: Fence> { /* private fields */ }Expand description
Defers the drop of CPU-side Bytes allocations until the device has
finished reading them.
§How it works
The device uploads are asynchronous: after you copy bytes into a staging buffer
and enqueue an upload command, the CPU memory must remain valid until the
device is done. PendingDropQueue manages this lifetime with a two-phase
approach:
- Stage – call
pushto hand over bytes that are in-flight. They land in thestagedlist. - Flush – call
flushto rotate the lists. The previously staged bytes move topending, a newFenceis created to mark the end of the current upload batch, and any bytes that were already pending (i.e. the batch before that) are freed after syncing the previous fence.
This double-buffer scheme means CPU memory is held for at most two flush cycles, while avoiding any unnecessary stalls on the hot path.
§Flushing policy
Call should_flush to check whether enough bytes
have accumulated to warrant a flush. You may also flush unconditionally
(e.g. at the end of a frame).
Implementations§
Source§impl<F: Fence> PendingDropQueue<F>
impl<F: Fence> PendingDropQueue<F>
Sourcepub fn new(policy: FlushingPolicy) -> Self
pub fn new(policy: FlushingPolicy) -> Self
Creates a new PendingDropQueue.
Sourcepub fn push(&mut self, bytes: Bytes)
pub fn push(&mut self, bytes: Bytes)
Enqueue bytes to be dropped once the device has finished reading them.
The bytes are added to the current staged batch and will be freed on
the flush cycle after the next call to flush.
Sourcepub fn should_flush(&self) -> bool
pub fn should_flush(&self) -> bool
Returns true when the staged batch is large enough to justify a
flush.
Sourcepub fn flush<Factory: Fn() -> F>(&mut self, factory: Factory)
pub fn flush<Factory: Fn() -> F>(&mut self, factory: Factory)
Rotate the double-buffer and free any memory the device is done with.
THE POOL IS ALREADY REUSING THESE BUFFERS; THE BLOCKING IS THE PROOF,
NOT THE REUSE. reserve_pinned hands out POOLED slices, so nothing here
is allocating fresh host memory per upload – the only thing this
function adds is the evidence that the device has finished reading a
slice before the pool may hand the same one out again. That is why the
stall it causes is queue-depth serialisation rather than a data
dependency, and why raising the threshold is not merely “flush less
often”: past the depth where the fence being waited on was recorded long
enough ago that the device has already passed it, the wait goes to
approximately zero rather than to a fraction of itself.
The cure that removes the reason for the flush rather than the frequency
of it is to stop staging per launch at all – see
docs/METADATA_CACHE.md in mary, which is where the 483 uploads a
decode step come from.
factory is called to produce a Fence. It should submit (or
record) a device signal command so that syncing the fence guarantees all
preceding device work is complete.