Bug 506215 - Update the progress reporting article
Change-Id: I5b1db6a928011d7c5100cd03f20294d96d3ab878
Signed-off-by: Stefan Xenos <sxenos@gmail.com>
diff --git a/Article-Progress-Monitors/article.html b/Article-Progress-Monitors/article.html
index 4b31cdc..53231d4 100644
--- a/Article-Progress-Monitors/article.html
+++ b/Article-Progress-Monitors/article.html
@@ -37,7 +37,7 @@
<br>
<p><b> By Stefan Xenos, Google</b> <br>
-April 19, 2016<font size="-1"></font> </p>
+October 19, 2016<font size="-1"></font> </p>
</blockquote>
@@ -194,6 +194,45 @@
}
</pre>
+<p>
+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.
+<p>
+For example, this code converts an IProgressMonitor to a SubMonitor while performing
+a guaranteed cancellation check:
+<pre>
+ SubMonitor subMonitor = SubMonitor.convert(monitor).checkCanceled();
+</pre>
+
+<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:
+<p>
+<pre>
+org.eclipse.equinox.common/debug=true
+org.eclipse.equinox.common/progress_monitors=true
+</pre>
+<p>
+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.
+<p>
+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:
+
+<pre>
+org.eclipse.core.internal.runtime.TracingOptions.debugProgressMonitors
+</pre>
+<p>
+More information about enabling Eclipse tracing options can be found
+<a href="https://wiki.eclipse.org/FAQ_How_do_I_use_the_platform_debug_tracing_facility">here</a>.
+
<h2>3.0 Examples</h2>
Lets look at some examples of common progress reporting patterns.
@@ -455,6 +494,7 @@
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 @@
<p>
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.
+<p>
+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>
