Skip to main content

PendingDropQueue

Struct PendingDropQueue 

Source
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:

  1. Stage – call push to hand over bytes that are in-flight. They land in the staged list.
  2. Flush – call flush to rotate the lists. The previously staged bytes move to pending, a new Fence is 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>

Source

pub fn new(policy: FlushingPolicy) -> Self

Creates a new PendingDropQueue.

Source

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.

Source

pub fn should_flush(&self) -> bool

Returns true when the staged batch is large enough to justify a flush.

Source

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.

Trait Implementations§

Source§

impl<E: Fence> Debug for PendingDropQueue<E>

Source§

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

Formats the value using the given formatter. Read more
Source§

impl<E: Fence> Default for PendingDropQueue<E>

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

§

impl<E> !RefUnwindSafe for PendingDropQueue<E>

§

impl<E> !UnwindSafe for PendingDropQueue<E>

§

impl<E> Freeze for PendingDropQueue<E>
where Option<E>: Freeze,

§

impl<E> Send for PendingDropQueue<E>
where Option<E>: Send,

§

impl<E> Sync for PendingDropQueue<E>
where Option<E>: Sync,

§

impl<E> Unpin for PendingDropQueue<E>
where Option<E>: Unpin,

§

impl<E> UnsafeUnpin for PendingDropQueue<E>
where Option<E>: UnsafeUnpin,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.