|author||Stefan Xenos||2016-10-19 11:00:35 -0400|
|committer||Stefan Xenos||2016-10-19 11:00:35 -0400|
Bug 506215 - Update the progress reporting article
Change-Id: I5b1db6a928011d7c5100cd03f20294d96d3ab878 Signed-off-by: Stefan Xenos <email@example.com>
1 files changed, 44 insertions, 1 deletions
diff --git a/Article-Progress-Monitors/article.html b/Article-Progress-Monitors/article.html
index 4b31cdc..53231d4 100644
@@ -37,7 +37,7 @@ of the API introduced in Eclipse 4.6.
<p><b> By Stefan Xenos, Google</b> <br>
-April 19, 2016<font size="-1"></font> </p>
+October 19, 2016<font size="-1"></font> </p>
@@ -194,6 +194,45 @@ additionally includes a cancellation check. Internally, split does something lik
+In some rare cases, you really need to perform an explicit cancellation check
+at a specific time and can't rely on the intermittent cancellation checks done
+by <code>split</code>. In such cases, you can use the <code>SubMonitor.checkCanceled</code>
+utility introduced in Eclipse 4.7.
+For example, this code converts an IProgressMonitor to a SubMonitor while performing
+a guaranteed cancellation check:
+ SubMonitor subMonitor = SubMonitor.convert(monitor).checkCanceled();
+<h3>2.5 Testing and Debugging</h3>
+Whenever you add or change progress monitoring in a method, you should test it by
+enabling the progress monitor self-tests while you run your code. To do this, add
+the following tracing options to an Eclipse .options file:
+Once enabled, you will see a warning written to the log whenever your code violates
+the API contracts on a SubMonitor. The tracing options can also be enabled in the
+<i>tracing</i> tab of any launch configuration. If you maintain any code that reports
+progress, it's generally a good idea to leave these options enabled at all times.
+If you see nothing it either means that your code is working perfectly or that the
+diagnostic tool isn't running. You can confirm that the diagnostic tool is running by
+using your debugger to confirm that the following variable is true:
+More information about enabling Eclipse tracing options can be found
Lets look at some examples of common progress reporting patterns.
@@ -455,6 +494,7 @@ or select a monitor implementation like SubMonitor which doesn't require the use
In Eclipse 4.7 (Oxygen) and higher, method implementations are not required to invoke
<code>done()</code>. Callers must either invoke <code>done()</code> or select a monitor
implementation like SubMonitor which doesn't require the use of <code>done()</code>.
<h3>5.1 Changes in Eclipse 4.6</h3>
@@ -515,6 +555,9 @@ in earlier versions.
Methods in plugins that are also intended for use with earlier Eclipse versions should continue calling
<code>done()</code> as long as those earlier Eclipse versions are still being supported by the plugin.
+Eclipse 4.7 also introduced the <code>SubMonitor.checkCanceled</code> utility for convenient
+explicit cancellation checks.
<h2>6.0 The protocol of <i>IProgressMonitor</i></h2>