public final class ProbingSubMonitor extends SubMonitor
sub monitor
that automatically collects and reports usage statistics.
It is normally very challenging to find out how much time a program really spends in the different parts of the monitored methods or how often these parts get executed. Stepping through the program with a debugger obviously leads to distortion that renders the observations meaningless and adding extra code to measure a runtime scenario realistically is not nice from a maintenance point of view.
As a solution to this problem this class offers the possibility to transparently instrument SubMonitor
instances such that they automatically
collect and report all kinds of statistics that may help to enhance the user experience. Sometimes it would even indicate to remove some progress monitoring
because it turns out that almost no time is being spent in a particular part of the program. Another typical result from the analysis is the understanding of
one time effects that might need special consideration.
Instances of this class can be created explicitly with the Progress.progress()
factory methods
that take a SubMonitor.ProbingMode
argument. Implicit (automatic) instrumentation can be controlled with the "submonitor.probing
"
system property
as follows:
off
monitors
that are not created with an explicit probing mode will not collect any usage information. No extra heap space
or CPU time is allocated to these monitors.
standard
monitors
that are not created with an explicit probing mode will collect and report only statistical usage information.
The amount of heap space allocated for this information is constant over time.
full
monitors
that are not created with an explicit probing mode will store and report all collected probes.
The amount of heap space allocated for this information scales with the number of monitor
instances that are created over time.
This class registers a shutdown hook
that dumps the probing results to the console when the program ends.
By setting the "submonitor.probing.trace
" system property
to the value "true
"
probing results are continuously dumped as they become available.
The probing results are formatted as tables per monitored method. Each row of a table corresponds to a call to the SubMonitor.worked()
or SubMonitor.newChild()
method. The first column of a table displays the location of that call, the content of the following columns depends on the probing mode used for a monitored method.
Example of the probing mode STANDARD
:
Example of the probing mode FULL
:
The tables in the two examples above have smooth borders that can only be displayed correctly in consoles with UTF-8 encoding. The console encoding
can be configured on the Common tab of the launch configuration dialog. In addition the rendering of smooth table borders must be explicitly enabled
by setting the "submonitor.probing.borders
" system property
to the value "smooth
".
Without this setting tables are rendered with "-", "+" and "|" characters that display correctly regardless of the console encoding.
Quick navigation from the table cells to the corresponding code locations is supported by clickable links in the console tables. This way the collected information can be converted into real enhancements of the monitoring code quickly and easily.
Important note: Avoid to load this class (i.e., to call any of its methods) unless you intend to actually use probing monitors. When this class is loaded it spawns a thread to collect unused progress monitors and to free up the heap space allocated to their probes. The shutdown hook mentioned above is also registered when this class is loaded.
SubMonitor.ProbingMode
DEFAULT_WORK, SUPPRESS_ALL_LABELS, SUPPRESS_BEGINTASK, SUPPRESS_NONE, SUPPRESS_SETTASKNAME, SUPPRESS_SUBTASK
UNKNOWN
Modifier and Type | Method and Description |
---|---|
void |
childDone() |
void |
done() |
static void |
reportStatistics() |
static void |
resetStatistics() |
String |
toString() |
void |
worked(int work) |
beginTask, clearBlocked, convert, convert, convert, convert, convert, convert, detectCancelation, detectCancelation, eq, internalWorked, isCanceled, newChild, newChild, newChild, setBlocked, setCanceled, setTaskName, setWorkRemaining, skipped, skipped, subTask, worked
public void worked(int work)
worked
in interface IProgressMonitor
worked
in class SubMonitor
public void done()
done
in interface IProgressMonitor
done
in class SubMonitor
public void childDone()
childDone
in class SubMonitor
public static void reportStatistics()
public static void resetStatistics()
Copyright (c) 2014 Eike Stepper (Berlin, Germany) and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html