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:

   public void move(File a, File b, IProgressMonitor pm) {
      try {
         pm.beginTask("Moving", 10);
         copy(a, b, new SubProgressMonitor(pm, 8));
         delete(a, new SubProgressMonitor(pm, 2));
      } finally {
         pm.done();
      }
   }

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.

See Also:

• FAQ How do I use progress monitors?

---

This FAQ was originally published in Official Eclipse 3.0 FAQs. Copyright 2004, Pearson Education, Inc. All rights reserved. This text is made available here under the terms of the Eclipse Public License v1.0.