Difference between revisions of "FAQ How do I use a SubProgressMonitor?"

From Eclipsepedia

Jump to: navigation, search
 
m
Line 11: Line 11:
 
guessing how long the file deletion will take in proportion to the  
 
guessing how long the file deletion will take in proportion to the  
 
rest of the task.
 
rest of the task.
 
  
 
But if every API method you call expects a fresh monitor, how do
 
But if every API method you call expects a fresh monitor, how do
Line 22: Line 21:
 
of progress, the <tt>SubProgressMonitor</tt> scales that
 
of progress, the <tt>SubProgressMonitor</tt> scales that
 
work in proportion to the number of parent work units available.
 
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
 
If you are lost at this point, it is probably best to look at a simple
Line 30: Line 28:
 
take 80 percent of the total time, and that the deletion will take 20  
 
take 80 percent of the total time, and that the deletion will take 20  
 
percent of the time:
 
percent of the time:
 +
 
<pre>
 
<pre>
 
   public void move(File a, File b, IProgressMonitor pm) {
 
   public void move(File a, File b, IProgressMonitor pm) {
Line 41: Line 40:
 
   }
 
   }
 
</pre>
 
</pre>
 +
 
The <tt>copy</tt> and <tt>delete</tt> methods, in turn, will call <tt>beginTask</tt>
 
The <tt>copy</tt> and <tt>delete</tt> methods, in turn, will call <tt>beginTask</tt>
 
on the <tt>SubProgressMonitor</tt> that was allocated to it. The <tt>copy</tt>
 
on the <tt>SubProgressMonitor</tt> that was allocated to it. The <tt>copy</tt>
Line 47: Line 47:
 
that it can report only eight units of work to the parent monitor and so it
 
that it can report only eight units of work to the parent monitor and so it
 
will scale reported work units accordingly.
 
will scale reported work units accordingly.
 
  
 
== See Also: ==
 
== See Also: ==
 
+
*[[FAQ How do I use progress monitors?]]
[[FAQ_How_do_I_use_progress_monitors%3F]]
+
  
 
<hr><font size=-2>This FAQ was originally published in [http://www.eclipsefaq.org Official Eclipse 3.0 FAQs]. Copyright 2004, Pearson Education, Inc. All rights reserved. This text is made available here under the terms of the [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License v1.0].</font>
 
<hr><font size=-2>This FAQ was originally published in [http://www.eclipsefaq.org Official Eclipse 3.0 FAQs]. Copyright 2004, Pearson Education, Inc. All rights reserved. This text is made available here under the terms of the [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License v1.0].</font>

Revision as of 22:15, 29 May 2006

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 {
         m.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:


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.