Bug 515780 - Minor updates to the progress monitor article
Change-Id: Icc86839557f6ca25f0154973776b0144b7a0c995
Signed-off-by: Stefan Xenos <sxenos@gmail.com>
diff --git a/Article-Progress-Monitors/article.html b/Article-Progress-Monitors/article.html
index 53231d4..92f8b10 100644
--- a/Article-Progress-Monitors/article.html
+++ b/Article-Progress-Monitors/article.html
@@ -196,7 +196,7 @@
<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
+at a specific time and can't rely on the sparse 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>
@@ -222,7 +222,7 @@
<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
+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:
@@ -430,7 +430,35 @@
Notice the idiom <code>setWorkRemaining(denominator).split(numerator)</code>. This can be used
at any point to consume numerator/denominator of the remaining space in a monitor.
-<h3>3.7 Naming conventions</h3>
+<h3>3.7 Try / catch / finally blocks</h3>
+
+What if you need to do something in a catch or finally block that reports progress?
+This is tricky since catch and finally blocks should almost never perform cancellation checks.
+Otherwise, they're likely to throw an <code>OperationCanceledException</code> while running the very
+code that reacts to <code>OperationCanceledException</code>. For this reason, you should use the
+<code>SUPPRESS_ISCANCELED</code> flag whenever creating a child monitor within a catch or finally
+block.
+
+<pre>
+ void tryFinallyBlockExample(IProgressMonitor monitor) {
+ SubMonitor subMonitor = SubMonitor.convert(monitor, 2);
+ try {
+ doOperation(subMonitor.split(1));
+ } catch (SomeException e) {
+ handleException(subMonitor.setWorkRemaining(2)
+ .split(1, SubMonitor.SUPPRESS_ISCANCELED | SubMonitor.SUPPRESS_BEGINTASK));
+ } finally {
+ doFinallyBlock(subMonitor
+ .split(1, SubMonitor.SUPPRESS_ISCANCELED | SubMonitor.SUPPRESS_BEGINTASK));
+ }
+ }
+</pre>
+
+Notice that this example also uses the <code>SUPPRESS_BEGINTASK</code> flag. When passing flags to
+<code>split</code> or <code>newChild</code>, you should always include the
+<code>SUPPRESS_BEGINTASK</code> flag unless you have a specific reason not to.
+
+<h3>3.8 Naming conventions</h3>
In these examples we've used the same naming convention that has been used within
the Eclipse platform. You may wish to use the same convention to help convey the purpose of your
