Jump to: navigation, search

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

 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
You shouldn't use SubProgressMonitor. You should use SubMonitor.
 +
More information about migrating SubProgressMonitor to SubMonitor
 +
can be found [https://eclipse.org/articles/Article-Progress-Monitors/article.html here]
 +
 
When using progress monitors in Eclipse, an important rule is that
 
When using progress monitors in Eclipse, an important rule is that
 
all API methods expect a fresh, unused progress monitor. You
 
all API methods expect a fresh, unused progress monitor. You
Line 14: Line 18:
 
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
 
you implement an operation that calls several such API methods?
 
you implement an operation that calls several such API methods?
The solution is to use a <tt>SubProgressMonitor</tt>,
+
The solution is to use a <tt>SubMonitor</tt>,
 
which acts as a bridge between caller and callee.
 
which acts as a bridge between caller and callee.
 
This monitor knows how many work units the parent has allocated for
 
This monitor knows how many work units the parent has allocated for
 
a given work task and how many units of work the
 
a given work task and how many units of work the
 
child task thinks it has.  When the child task reports a unit
 
child task thinks it has.  When the child task reports a unit
of progress, the <tt>SubProgressMonitor</tt> scales that
+
of progress, the <tt>SubMonitor</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.
  
Line 30: Line 34:
  
 
<pre>
 
<pre>
   public void move(File a, File b, IProgressMonitor pm) {
+
   public void move(File a, File b, IProgressMonitor monitor) {
       try {
+
       SubMonitor subMonitor = SubMonitor.convert(monitor, 10);
        pm.beginTask("Moving", 10);
+
      copy(a, b, subMonitor.split(8));
        copy(a, b, new SubProgressMonitor(pm, 8));
+
      delete(a, subMonitor.split(2));
        delete(a, new SubProgressMonitor(pm, 2));
+
      } finally {
+
        pm.done();
+
      }
+
 
   }
 
   }
 
</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>SuMonitor</tt> that was allocated to it. The <tt>copy</tt>
 
method might decide to report one unit of work for each 8KB chunk of the file.
 
method might decide to report one unit of work for each 8KB chunk of the file.
Regardless of the size of the file, the <tt>SubProgressMonitor</tt> knows
+
Regardless of the size of the file, the <tt>SubMonitor</tt> knows
 
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.
Line 51: Line 51:
 
*[[FAQ How do I use progress monitors?]]
 
*[[FAQ How do I use progress monitors?]]
  
<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>
+
{{Template:FAQ_Tagline}}

Latest revision as of 12:32, 22 April 2016

You shouldn't use SubProgressMonitor. You should use SubMonitor. More information about migrating SubProgressMonitor to SubMonitor can be found here

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 SubMonitor, 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 SubMonitor 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 monitor) {
      SubMonitor subMonitor = SubMonitor.convert(monitor, 10);
      copy(a, b, subMonitor.split(8));
      delete(a, subMonitor.split(2));
   }

The copy and delete methods, in turn, will call beginTask on the SuMonitor 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 SubMonitor 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.