Struct EventProfiler 

pub struct EventProfiler<A: EventApi> { /* private fields */ }

Device profiling on the GPU’s own clock.

A profiling window is two events recorded into the stream where the window opened and closed. Nothing on the host waits for them: the device stamps each one as the queue reaches it, and the span between the two is read back later, by whoever awaits the measurement.

That deferral is what makes a measurement mean something when profiles nest. The system-time profiler has to drain the stream at both ends of every window to have anything to time, so an inner window’s two drains happen inside the outer one and are charged to it: the outer measurement grows with the number of inner ones, and every window reads back the launch latency the drain exposed rather than the work. Events are recorded in-queue and cost the host nothing, so an inner window measures its own kernels and the outer one measures the work rather than the profiling.

The state is the windows currently open, and the anchor that places them on the host clock.

Implementations

impl<A: EventApi> EventProfiler<A>

pub fn start( &mut self, stream: A::Stream, ) -> Result<ProfilingToken, ServerError>

Open a window at the current position of stream.

Errors

ServerError when the device refuses an event or the stream will not record one. No window is opened and no token is issued, so the caller owes nothing; the events involved return to the pool.

pub fn stop( &mut self, stream: A::Stream, token: ProfilingToken, ) -> Result<ProfileDuration, ProfileError>

Close the window token opened at the current position of stream.

Returns at enqueue time. The duration is read from the device by the returned future, which is where the wait for the window’s work lives.

That future blocks the thread that polls it: the device APIs offer no way to be woken when an event is reached, only a synchronize that parks the caller, so the first poll returns once the device has reached both events. Await it from a thread that can afford to wait — the same place a synchronize would have gone.

Errors

ProfileError::NotRegistered for a token this profiler never issued or has already closed, the error registered against the window by failure when device work failed inside it, and ProfileError::Server when the closing event cannot be recorded. There is nothing to measure in any of those cases and the window is gone either way.

pub fn abandon(&mut self, token: ProfilingToken)

Drop the window token opened without measuring it, for a caller that has no way to record its end.

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

Mark every open window invalid because device work failed.

This is what keeps a tuning candidate that failed from benchmarking at close to zero and winning the tune. A no-op with no window open, so a failure path calls it unconditionally and pays nothing for the common case of no measurement in flight.

Trait Implementations

impl<A: EventApi> Debug for EventProfiler<A>

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

Formats the value using the given formatter.

impl<A: EventApi> Default for EventProfiler<A>

fn default() -> Self

Returns the “default value” for a type.