FAQ How do I use a SubProgressMonitor?

When using progress monitors in Eclipse, an important rule is that
all API methods expect a fresh, unused progress monitor. You
cannot pass them a monitor that has had beginTask called
on it or a monitor that has already recorded some units of work.
The reasons for this are clear. API methods can be called from a
variety of places and cannot predict how many units of
work they represent in the context of a long-running operation.
An API method that deletes a file might represent all the work
for an operation or might be called as a small part of a much larger
operation. Only the code at the top of the call chain has any way of
guessing how long the file deletion will take in proportion to the
rest of the task.

But if every API method you call expects a fresh monitor, how do
you implement an operation that calls several such API methods?
The solution is to use a SubProgressMonitor,
which acts as a bridge between caller and callee.
This monitor knows how many work units the parent has allocated for
a given work task and how many units of work the
child task thinks it has. When the child task reports a unit
of progress, the SubProgressMonitor scales that
work in proportion to the number of parent work units available.

If you are lost at this point, it is probably best to look at a simple
example. This fictional move method is implemented
by calling a copy method, followed by a delete
method. The move method estimates that the copying will
take 80 percent of the total time, and that the deletion will take 20
percent of the time:

The copy and delete methods, in turn, will call beginTask
on the SubProgressMonitor that was allocated to it. The copy
method might decide to report one unit of work for each 8KB chunk of the file.
Regardless of the size of the file, the SubProgressMonitor knows
that it can report only eight units of work to the parent monitor and so it
will scale reported work units accordingly.