Skip to content
xc

Progress

Progress reports how far a piece of work has got, as a tree (NSProgress in shape). From 0.72.

#import "Progress.xc"      // not in the Foundation umbrella: import it by name

Overview

Section titled “Overview”
Progress* whole = Progress.withTotal((i64)10);       // ten units of work
Progress* files = whole.makeChild((i64)200, (i64)6);  // 200 files, worth 6 of the 10
files.incrementBy((i64)100);                          // half the files
whole.incrementBy((i64)2);                            // 2 units of whole's own work
whole.fractionCompleted();                            // (2 + 0.5 × 6) / 10 = 0.5

A progress has a total and a completed count of units in whatever measure suits it (bytes, files, steps), and may hand a share of its units to child progresses that count in their own measure. The fraction completed rolls the children up: a child halfway through contributes half the units it was given. A long operation reports coarse progress and gives slices to the parts that do the work; whoever draws a bar reads the root.

A total of 0 or less is indeterminate: the work cannot yet say how much there is. Cancelling a progress cancels its children; the work checks isCancelled and stops.

A progress is for one thread, usually the run loop’s: a worker reports its counts to that thread rather than updating the tree itself.

Topics

Section titled “Topics”

Creating · withTotal

Counting · totalUnitCount / setTotalUnitCount · completedUnitCount / setCompletedUnitCount · incrementBy

Children · addChild · makeChild

Reading · fractionCompleted · fractionPerMille · isIndeterminate · isFinished

Cancelling · cancel / isCancelled

Creating

Section titled “Creating”

withTotal

Section titled “withTotal”
static Progress* withTotal(i64 total)

A progress of total units, none done. new Progress() is indeterminate.

↑ Topics

Counting

Section titled “Counting”

totalUnitCount / setTotalUnitCount

Section titled “totalUnitCount / setTotalUnitCount”
i64 totalUnitCount(void)
void setTotalUnitCount(i64 n)

completedUnitCount / setCompletedUnitCount

Section titled “completedUnitCount / setCompletedUnitCount”
i64 completedUnitCount(void)
void setCompletedUnitCount(i64 n)

The units done directly, not counting children.

incrementBy

Section titled “incrementBy”
void incrementBy(i64 n)

↑ Topics

Children

Section titled “Children”

addChild

Section titled “addChild”
void addChild(Progress* child, i64 units)

Hands units of this progress’s total to child, which counts in its own measure. A child added to a cancelled progress is cancelled.

makeChild

Section titled “makeChild”
Progress* makeChild(i64 total, i64 units)

A new child of total units of its own, standing for units of this progress’s.

↑ Topics

Reading

Section titled “Reading”

fractionCompleted

Section titled “fractionCompleted”
double fractionCompleted(void)

0.0 to 1.0: the progress’s own completed units plus each child’s fraction times its units, over the total, kept within 0 and 1. 0 when indeterminate.

fractionPerMille

Section titled “fractionPerMille”
u32 fractionPerMille(void)

The fraction in thousandths, 0 to 1000, rounded down: for a bar drawn in whole steps.

isIndeterminate

Section titled “isIndeterminate”
bool isIndeterminate(void)

Whether the total is not known yet (0 or less).

isFinished

Section titled “isFinished”
bool isFinished(void)

Whether the fraction has reached 1.

↑ Topics

Cancelling

Section titled “Cancelling”

cancel / isCancelled

Section titled “cancel / isCancelled”
void cancel(void)
bool isCancelled(void)

Marks this progress and every child cancelled; the work is expected to notice and stop.

↑ Topics