Up
Authors
- Hugo Melder (
hugo@algoriddim.com)
-
Date: Generated at 2025-12-03
Copyright: (C) 2025 Free Software Foundation, Inc.
- Declared in:
- Foundation/NSProgress.h
Availability: MacOS-X 10.9.0
A progress object tracks an amount of work that is yet to
be completed. Work is tracked in units. A progress is
finished when the completed number of unit work is
equal to the total number of unit work. Progress
objects can be arranged in a tree formation. Children
of a parent progress continuosly report their progress and
update the parents fractionCompleted property. When a
child is added to a parent progress, a pending unit
count is specified. This count is added to the parent
after completion of the child. There are two mechanisms
to add a progress as a child to another progress object:
One can explicitly add a child with
-addChild:withPendingUnitCount:
. There is also a way to implicitly add newly instantiated
progress object as a child to an existing progress.
For this, we first need to define how the
"currentProgress" API works: Every thread
has a thread-specific current progress stack. The
top-most element on this stack can be accessed by
+currentProgress
class method. By sending
-becomeCurrentWithPendingUnitCount:
to a progress, the progress object is pushed onto the
stack and becomes the new current progress. The next
progress object instantiated (excluding creation
with discreteProgressWithTotalUnitCount:) becomes a
child of this current progress. This is the second
mechanism to implicitly add a child to a progress
object.
Implementation Note: GNUstep
currently, as of August 2025, lacks the ability to
create RW locks. RW locks would make the NSProgress
implementation more efficient, as getters (and
other readers) could request shared, instead of
exclusive access. While not explicitly mentioned in
the Apple API documentation, NSProgress relies on a
per-object NSLock to synchronize progress update
operations. Apple's API documentation is terrible
for the NSProgress implementation, as it does not
describe important implementation details and
side-effects. To give you an example, there is
no mention of the usage of a thread-specific stack for
current progress. We conducted experiments on macOS
15.5 to match this implementation with the one present
in Foundation.
+ (id)
addSubscriberForFileURL: (
NSURL*)url
withPublishingHandler: (NSProgressPublishingHandler)publishingHandler;
Availability: MacOS-X 10.9.0
Description forthcoming.
+ (
NSProgress*)
currentProgress;
Availability: MacOS-X 10.9.0
Retrieve the first progress object that is on the
thread-local current progress stack.
+ (
NSProgress*)
discreteProgressWithTotalUnitCount: (int64_t)unitCount;
Availability: MacOS-X 10.9.0
Creates a progress object for a total number of
work units. This object will not be part of an
existing progress tree. This object cannot
implicitly become a child of the current
progress, even if the current progress expects
the next created progress object to be an implicit
child.
+ (
NSProgress*)
progressWithTotalUnitCount: (int64_t)unitCount;
Availability: MacOS-X 10.9.0
Creates a progress object for a total number of
work units. Note that this object may become an
implicit child of the thread-local current
progress object, if requested by the current
progress object.
+ (
NSProgress*)
progressWithTotalUnitCount: (int64_t)unitCount
parent: (
NSProgress*)parent
pendingUnitCount: (int64_t)portionOfParentTotalUnitCount;
Availability: MacOS-X 10.9.0
Creates a progress object for a total number of
work units. This object is then added as a child to
the parent with a pending number of units.
+ (void)
removeSubscriber: (id)subscriber;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (void)
addChild: (
NSProgress*)child
withPendingUnitCount: (int64_t)inUnitCount;
Availability: MacOS-X 10.9.0
Adds the progress to the receiver as a
child. The pending unit count is added to
the receiver upon completion of the child
progress. The pending unit count should not
exceed the receivers total unit count. However, this
is not enforced in Apple's NSProgress implementation.
- (void)
becomeCurrentWithPendingUnitCount: (int64_t)unitCount;
Availability: MacOS-X 10.9.0
Push the receiver to the thread-local current progress
stack. The first object on the stack can be accessed
with +[NSProgress currentProgress]. Upon
initialisation of the next progress object,
the newly created object becomes a child of receiver.
Note that this only holds for the first object
created. If the child progress completes, the
pending unit count is added to the receiver. The
pending unit count represents the portion of work
to perform in relation to the total number of units of
work, which is the value of the receivers
totalUnitCount property. The pending units
of work should be less than or equal to the total units
of work of the receiver. Ensure that the total number is
not exceeded. Calls to this method must be matched by
-[NSProgress resignCurrent].
- (void)
cancel;
Availability: MacOS-X 10.9.0
Cancels tracking by the receiver (so subsequent
calls to
-isCancelled
will return
YES), and also cancels
unfinished children. If a cancellation handler
is set, it will be called before cancelling child
progresses.
- (int64_t)
completedUnitCount;
Availability: MacOS-X 10.9.0
Returns the number of unit work already completed.
- (
NSNumber*)
estimatedTimeRemaining;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (
NSNumber*)
fileCompletedCount;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (
NSNumber*)
fileTotalCount;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (
NSURL*)
fileUrl;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (double)
fractionCompleted;
Availability: MacOS-X 10.9.0
Provides a fraction of completed work, including
work done by child progresses. Different from the
completedUnitCount property, this
property is continuously updated, tracking the
progress of children as well.
- (instancetype)
initWithParent: (
NSProgress*)parent
userInfo: (
NSDictionary*)userInfo;
Availability: MacOS-X 10.9.0
Instantiate a new progress object by optionally
supplying a parent and user
information dictionary. The parent
progress must either be the current progress
object of the current thread, or nil.
- (BOOL)
isCancellable;
Availability: MacOS-X 10.9.0
Indicates whether the underlying work whose
progress is being tracked can be cancelled. This
has no effect on whether the receiver can be cancelled.
By default, a progress instance assumes that the work is
cancellable but not pausable.
Progress
Cancellation
- (BOOL)
isCancelled;
Availability: MacOS-X 10.9.0
Returns YES if the reciever has been
cancelled.
- (BOOL)
isFinished;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (BOOL)
isIndeterminate;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (BOOL)
isOld;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (BOOL)
isPausable;
Availability: MacOS-X 10.9.0
Pausation of a progress is not implemented. This
method always returns 'NO'.
Progress
Pausation (Not Implemented)
- (BOOL)
isPaused;
Availability: MacOS-X 10.9.0
Pausation of a progress is not implemented.
Therefore a progress is never paused and this
method always returns 'NO'.
- (
NSProgressKind)
kind;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (
NSString*)
localizedAdditionalDescription;
Availability: MacOS-X 10.9.0
Returns the additional localized description
string.
- (
NSString*)
localizedDescription;
Availability: MacOS-X 10.9.0
Returns the localized description string.
- (void)
pause;
Availability: MacOS-X 10.9.0
Pausation of a progress is not implemented. This
method will throw an exception.
- (void)
performAsCurrentWithPendingUnitCount: (int64_t)unitCount
usingBlock: (GSProgressPendingUnitCountBlock)work;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (void)
publish;
Availability: MacOS-X 10.9.0
The progress discovery functionality is not
implemented. This method will throw an
exception.
- (void)
resignCurrent;
Availability: MacOS-X 10.9.0
Receiver resigns the role of the current progress.
The receiver is popped from the thread-local current
progress stack. If the receiver is not the current
progress, an exception will be thrown.
- (void)
resume;
Availability: MacOS-X 10.9.0
Progress Resumption (Not Implemented)
- (void)
setCancellable: (BOOL)cancellable;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (void)
setCancellationHandler: (GSProgressCancellationHandler)handler;
Availability: MacOS-X 10.9.0
Sets a cancellation handler that is called
when a progress gets cancelled.
- (void)
setCompletedUnitCount: (int64_t)unitCount;
Availability: MacOS-X 10.9.0
Updates the number of unit work already completed.
Monotonicity of this count is not enforced.
- (void)
setEstimatedTimeRemaining: (
NSNumber*)n;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (void)
setFileCompletedCount: (
NSNumber*)n;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (void)
setFileTotalCount: (
NSNumber*)n;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (void)
setFileUrl: (
NSURL*)u;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (void)
setKind: (
NSProgressKind)k;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (void)
setLocalizedAdditionalDescription: (
NSString*)addDesc;
Availability: MacOS-X 10.9.0
Sets the additional localized description string.
- (void)
setLocalizedDescription: (
NSString*)desc;
Availability: MacOS-X 10.9.0
Sets the localized description string.
- (void)
setPausingHandler: (GSProgressPausingHandler)handler;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (void)
setResumingHandler: (GSProgressResumingHandler)handler;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (void)
setThroughput: (
NSNumber*)n;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (void)
setTotalUnitCount: (int64_t)unitCount;
Availability: MacOS-X 10.9.0
Sets the total nubmer of unit work to be tracked by
the receiver.
- (void)
setUserInfoObject: (id)obj
forKey: (
NSProgressUserInfoKey)key;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (
NSNumber*)
throughput;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (int64_t)
totalUnitCount;
Availability: MacOS-X 10.9.0
Returns the total number of unit work to be tracked
by the receiver.
- (void)
unpublish;
Availability: MacOS-X 10.9.0
Description forthcoming.
- (
NSDictionary*)
userInfo;
Availability: MacOS-X 10.9.0
Description forthcoming.
- Declared in:
- Foundation/NSProgress.h
Availability: MacOS-X 10.9.0
Description forthcoming.
- (
NSProgress*)
progress;
Availability: MacOS-X 10.9.0
Description forthcoming.
Up