NSProgress Documentation Conflicts

Curtis Herbert:

Wait...what? The new NSProgress stuff on NSOperationQueue says you have to call super.start() to contribute towards progress, but Foundation docs for NSOperation say to never call super.start() O.o

NSOperation.h:

The progress property represents a total progress of the operations executed in the queue. By default NSOperationQueue does not report progress until the totalUnitCount of the progress is set. When the totalUnitCount property of the progress is set the queue then opts into participating in progress reporting. When enabled, each operation will contribute 1 unit of completion to the overall progress of the queue for operations that are finished by the end of main (operations that override start and do not invoke super will not contribute to progress).

NSOperation documentation:

At no time in your start method should you ever call super. When you define a concurrent operation, you take it upon yourself to provide the same behavior that the default start method provides, which includes starting the task and generating the appropriate KVO notifications.

Matej Bukovinski:

Let’s just replace a NSProgress helper with built-in API. Easy. A day later we’re still trying to figure out if we even know how this API is supposed to be used. Spoiler: The header is right. As usual. Never rely just on the generated docs.

NSProgress.h:

-isIndeterminate returns YES when the value of the totalUnitCount or completedUnitCount property is less than zero. Zero values for both of those properties indicates that there turned out to not be any work to do after all; -isIndeterminate returns NO and -fractionCompleted returns 1.0 in that case.

NSProgress documentation:

Progress is indeterminate when the value of both totalUnitCount and completedUnitCount are zero.

Previously:

• NSProgress
• An Example on How to Use NSProgress
• NSProgress Enhancements
• NSProgress Shortcomings and CSProgress

Update (2020-05-06): Peter Steinberger:

UIKit folks, there’s a radar from 2017 about wrongly documented NSProgress API.

Update (2020-05-19): Noah Gilmore:

Oh man, this just reminded me of a nasty customer-facing issue we fixed with NSProgress. Turns out that if you set completedUnitCount too many times on a background thread, app’s memory grows uncontrollably and eventually hits the memory limit 😨

Cocoa Documentation iOS iOS 13 Mac macOS 10.15 Catalina NSProgress Programming

Comments RSS · Twitter

Leave a Comment

Name

E-mail (will not be published)

Web site

Δ