HexFiend
Instance Methods | Properties | List of all members
HFProgressTracker Class Reference

A class that helps handle progress indication and cancellation for long running threaded operations. More...

Inheritance diagram for HFProgressTracker:

Instance Methods

(void) - beginTrackingProgress
 
(void) - endTrackingProgress
 
(void) - noteFinished:
 
(void) - requestCancel:
 

Properties

unsigned long long maxProgress
 
NSDictionary * userInfo
 
NSProgressIndicator * progressIndicator
 
id delegate
 

Detailed Description

HFProgressTracker is a class that helps handle progress indication and cancellation for long running threaded operations, while imposing minimal overhead. Operations such as Find/Replace or Save take an HFProgressTracker to provide cancellation and progress reporting.

The thread is expected to write directly into the public currentProgress field (perhaps with atomic functions) as it makes progress. Once beginTrackingProgress is called, the HFProgressTracker will poll currentProgress until endTrackingProgress is called.

The thread is also expected to read directly from cancelRequested, which is set by the requestCancel method. If requestCancel is set, it should end the operation.

Lastly, the thread is expected to call noteFinished: when it is done, either through cancellation or completing normally.

On the client side, you can set a delegate. progressTracker: didChangeProgressTo: is called on your delegate at regular intervals in the main thread, as the progress changes. Likewise, progressTrackerDidFinish: is called on the main thread after noteFinished: is called.

There is also a progressIndicator property, which if set to an NSProgressIndicator will cause it to be updated regularly.

Method Documentation

§ beginTrackingProgress()

- (void) beginTrackingProgress

Called to indicate you want to begin tracking the progress, which means that the progress indicator will be updated, and the delegate callbacks may fire.

§ endTrackingProgress()

- (void) endTrackingProgress

Called to indicate you want to end tracking progress. The progress indicator will no longer be updated.

§ noteFinished:()

- (void) noteFinished: (id)  sender

noteFinished: should be called by the thread when it is done. It is safe to call this from the background thread.

§ requestCancel:()

- (void) requestCancel: (id)  sender

requestCancel: may be called to mark the cancelRequested variable. The thread should poll this variable to determine if it needs to cancel.

Property Documentation

§ maxProgress

- (unsigned long long) maxProgress
readwritenonatomicassign

HFProgressTracker determines the progress as an unsigned long long, but passes the progress to the delegate as a double, which is computed as the current progress divided by the max progress.

§ userInfo

- (NSDictionary*) userInfo
readwritenonatomiccopy

The userInfo property is a convenience to allow passing information to the thread. The property is not thread safe - the expectation is that the main thread will set it before the operation starts, and the background thread will read it once after the operation starts.

§ progressIndicator

- (NSProgressIndicator*) progressIndicator
readwritenonatomicstrong

The progressIndicator property allows an NSProgressIndicator to be associated with the HFProgressTracker. The progress indicator should have values in the range 0 to 1, and it will be updated with the fraction currentProgress / maxProgress.

§ delegate

- (id) delegate
readwritenonatomicassign

Set and get the delegate, which may implement the optional methods below.


The documentation for this class was generated from the following file: