Skip to main content
summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorStefan Xenos2017-04-25 13:32:16 -0400
committerStefan Xenos2017-04-25 13:32:55 -0400
commitb6f002c293acceac388e11e128c5d621dc344298 (patch)
tree6ed0e5d78a6d5d0bd5e9a3c43df2aebae3613bce
parent124697f3844775d8560ae4dc248700f07e2aa09a (diff)
downloadarticles-b6f002c293acceac388e11e128c5d621dc344298.tar.gz
articles-b6f002c293acceac388e11e128c5d621dc344298.tar.xz
articles-b6f002c293acceac388e11e128c5d621dc344298.zip
Bug 515780 - Minor updates to the progress monitor article
Change-Id: Icc86839557f6ca25f0154973776b0144b7a0c995 Signed-off-by: Stefan Xenos <sxenos@gmail.com>
-rw-r--r--Article-Progress-Monitors/article.html34
1 files changed, 31 insertions, 3 deletions
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 @@ additionally includes a cancellation check. Internally, split does something lik
<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 @@ the API contracts on a SubMonitor. The tracing options can also be enabled in th
<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 @@ long it will take? Try allocating a small percentage of the remaining space on e
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

Back to the top