Struct yield_progress::YieldProgress

pub struct YieldProgress { /* private fields */ }

Allows a long-running async task to report its progress, while also yielding to the scheduler (e.g. for single-threaded web environment) and introducing cancellation points.

These things go together because the rate at which it makes sense to yield (to avoid event loop hangs) is similar to the rate at which it makes sense to report progress.

Note that while a YieldProgress is Send and Sync in order to be used within tasks that may be moved between threads, it does not currently support meaningfully being used from multiple threads or futures at once — only within a fully sequential operation. Future versions may include a “parallel split” operation but the current one does not.

Implementations

impl YieldProgress

pub fn new<Y, YFut, P>(yielder: Y, progressor: P) -> Selfwhere Y: Fn() -> YFut + Send + Sync + 'static, YFut: Future<Output = ()> + Send + 'static, P: Fn(f32, &str) + Send + Sync + 'static,

Construct a new YieldProgress, which will call yielder to yield and progressor to report progress.

• yielder should return a Future that returns Poll::Pending at least once, and may perform other executor-specific actions to assist with scheduling other tasks.
• progressor is called with the progress fraction (a number between 0 and 1) and a label for the current portion of work (which will be "" if no label has been set).

It will also report any excessively-long intervals between yields using the log library. “Excessively long” is currently defined as 100 ms. The first interval starts when function is called, as if this is the first yield. This may become more configurable in future versions.

pub fn noop() -> Self

Returns a YieldProgress that does no progress reporting and no yielding.

pub fn set_label(&mut self, label: impl Display)

Add a name for the portion of work this YieldProgress covers, which will be used by all future progress updates.

If there is already a label, it will be overwritten.

This does not immediately report progress; that is, the label will not be visible anywhere until the next operation that does. Future versions may report it immediately.

pub fn progress( &self, progress_fraction: f32 ) -> impl Future<Output = ()> + Send + 'static

Report the current amount of progress (a number from 0 to 1) and yield.

The value may be less than previously given values.

pub fn progress_without_yield(&self, progress_fraction: f32)

Report the current amount of progress (a number from 0 to 1) without yielding.

Caution: Not yielding may mean that the display of progress to the user does not update. This should be used only when necessary for non-async code.

pub fn yield_without_progress( &self ) -> impl Future<Output = ()> + Send + 'static

Yield only; that is, call the yield function contained within this YieldProgress.

pub fn finish(self) -> impl Future<Output = ()> + Send + 'static

Report that 100% of progress has been made.

This is identical to .progress(1.0) but consumes the YieldProgress object.

pub fn finish_and_cut( self, progress_fraction: f32 ) -> impl Future<Output = Self> + Send + 'static

Report that the given amount of progress has been made, then return a YieldProgress covering the remaining range.

pub fn start_and_cut( &mut self, cut: f32, label: impl Display ) -> impl Future<Output = Self> + Send + 'static

Report the beginning of a unit of work of size progress_fraction and described by label. That fraction is cut off of the beginning range of self, and returned as a separate YieldProgress.

let a_progress = main_progress.start_and_cut(0.5, "task A").await;
// do task A...
a_progress.finish().await;
// continue using main_progress...

pub fn split(self, cut: f32) -> [Self; 2]

Construct two new YieldProgress which divide the progress value into two subranges.

The returned instances should be used in sequence, but this is not enforced.

pub fn split_evenly(self, count: usize) -> impl Iterator<Item = YieldProgress>

Split into even subdivisions.

Trait Implementations

impl Debug for YieldProgress

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

Formats the value using the given formatter.