|
Progress Pile
version 0.0.1
Progress pile.
|
Report progress. More...
#include <progress.h>
Public Member Functions | |
| Progress () | |
| Constructor; creates an empty progress object. | |
| virtual | ~Progress () |
| Destructor; releases all resources. | |
| bool | init (const QString &title=QString(), int64_t total_size=100) |
| Prepares the progress for a run. More... | |
| void | end () |
| Terminate a run (clear internal states). | |
| bool | isInitialized () const |
| Teell if the instance was initialized (init() was called). | |
| void | enter (int64_t parent_size, const QString &label=QString(), int64_t total_size=100, int64_t parent_offset=-1, void *portion_data=NULL) |
| Enters a new portion. More... | |
| void | finish (bool update_parent=true) |
| Ends current portion; calls end() if this is the last one. More... | |
| const QString & | currentStatus () const |
| Tell the label for current operation. | |
| int | cutoffLevel () const |
| Size of the active portion of the stack. | |
| void | setCutoffLevel (int value) |
| Size of the active portion of the stack. | |
| int64_t | granularity () const |
| Emit signals when progress advances by at least this much. | |
| void | setGranularity (int64_t value) |
| Emit signals when progress advances by at least this much. | |
| void * | userData () const |
| User data associated with the instance. | |
| void | setUserData (void *value) |
| User data associated with the instance. | |
| KbSignalSimple | simpleCallback () const |
| Simple callback to be used when progress changes. | |
| void | setSimpleCallback (KbSignalSimple value) |
| Simple callback to be used when progress changes. | |
| KbSignal | callback () const |
| Callback to be used when progress changes. | |
| void | setCallback (KbSignal value) |
| Callback to be used when progress changes. | |
| bool | step (int64_t chunk_size=1, int64_t offset=-1) |
| Perform a step in the context of top portion. More... | |
| void | setStop () |
| Sets the internal state to signal the process should terminate. | |
| void | resetStop () |
| Resets the internal state to signal the process should terminate. | |
| bool | shouldStop () const |
| Tell if the process / operation should stop. | |
| bool | emitSigal () |
| Force emmit a signal bypassing all checks (granularity, stack). More... | |
| void | setLevelCharact (int64_t total_size, int64_t progress=0) |
| Set characteristics for current level. More... | |
Report progress.
The class helps in keeping track of an asynchronous operation. It divides the task (total_progress_) into portions and has a current portion defined by an offset and a size. The progress that is reported is scaled inside the portion and the offset is applied for the final report.
The mechanism allows the caller to initialize the structure, set current portion then allow the subtask to report the progress without knowing anything about its internals or size. The parent task only decides how much of its progress the subtask is going to take.
The class does not store a list for each level and stepping to a new portion removes previous portion at the same level.
The label for current operation is given by first non-empty label that was provided, starting from the last portion. Thus sub-tasks have the option to leave the label empty, thus inheriting the text from the parent. In practive this value is cachec in current_status_ to avoid recursive search each time.
To use the class for a simple task that only has a single level simply call init () at the beginning, step() in the loop and finish () at the end.
The user has the ability to control the number of signals the class emits by choosing the maximum depth of the stack for which the signals are emited (0 disables the signals) and by choosing the granularity (the total progress must advance by at least that much to trigger a signal). By default all levels emit signals and the granularity is 1.
|
inline |
Force emmit a signal bypassing all checks (granularity, stack).
| void Progress::enter | ( | int64_t | parent_size, |
| const QString & | label = QString (), |
||
| int64_t | total_size = 100, |
||
| int64_t | parent_offset = -1, |
||
| void * | portion_data = NULL |
||
| ) |
Enters a new portion.
If the instance was not initialized the method will do that before proceeding.
| parent_size | |
| total_size | |
| parent_offset | |
| label | |
| portion_data |
| void Progress::finish | ( | bool | update_parent = true | ) |
Ends current portion; calls end() if this is the last one.
| update_parent |
| bool Progress::init | ( | const QString & | title = QString (), |
| int64_t | total_size = 100 |
||
| ) |
Prepares the progress for a run.
The function creates a first entry in the stack and initializes with offset 0 and provided size.
The caller does not need to call end () as the functions starts by doing that.
| title | The name of this job; will be shown when the subtasks do not provide their own title. |
| total_size | Total size of this task; the progress will be in same units as this value. |
|
inline |
Set characteristics for current level.
This method is useful when the parent passes to the child a Progress instance that has already been prepared by calling enter(). The child process then may need to adjust the values for the total span and (less likely) the position.
| total_size | |
| progress |
| bool Progress::step | ( | int64_t | chunk_size = 1, |
| int64_t | offset = -1 |
||
| ) |
Perform a step in the context of top portion.
Advances the progress for current portion if offset is negative by given chunk size or sets the progress for current portion by summing the offset and the size of the chunk.
The user can use this method in two ways. The progress can be updated by only providing the size of the chunk:
The progres can alternatively be set directly:
| chunk_size | Size of current portion not including the provious work. |
| offset | Previous work (use cached value by default). |