org.eclipse.oomph.util

## Class ProbingSubMonitor

- java.lang.Object
- - org.eclipse.oomph.util.SubMonitor
  - - org.eclipse.oomph.util.ProbingSubMonitor

- All Implemented Interfaces:
    IProgressMonitor, IProgressMonitorWithBlocking

      public final class ProbingSubMonitor
      extends SubMonitor

  An instrumented `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 realisticly 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 explicitely 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`
    All `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`
    All `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`
    All `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 explicitely 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.

  Author:
    Eike Stepper

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.eclipse.oomph.util.SubMonitor

      `SubMonitor.ProbingMode`

  - ### Field Summary

    - ### Fields inherited from class org.eclipse.oomph.util.SubMonitor

      `DEFAULT_WORK, SUPPRESS_ALL_LABELS, SUPPRESS_BEGINTASK, SUPPRESS_NONE, SUPPRESS_SETTASKNAME, SUPPRESS_SUBTASK`

    - ### Fields inherited from interface org.eclipse.core.runtime.IProgressMonitor

      `UNKNOWN`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `childDone()`
    `void` | `done()`
    `static void` | `reportStatistics()`
    `static void` | `resetStatistics()`
    `String` | `toString()`
    `void` | `worked(int work)`

    - ### Methods inherited from class org.eclipse.oomph.util.SubMonitor

      `beginTask, clearBlocked, convert, convert, convert, convert, convert, convert, detectCancelation, detectCancelation, eq, internalWorked, isCanceled, newChild, newChild, newChild, setBlocked, setCanceled, setTaskName, setWorkRemaining, skipped, skipped, subTask, worked`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### worked

          public void worked(int work)

      Specified by:
        `worked` in interface `IProgressMonitor`
      Overrides:
        `worked` in class `SubMonitor`

    - #### done

          public void done()

      Specified by:
        `done` in interface `IProgressMonitor`
      Overrides:
        `done` in class `SubMonitor`

    - #### childDone

          public void childDone()

      Overrides:
        `childDone` in class `SubMonitor`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### reportStatistics

          public static void reportStatistics()

    - #### resetStatistics

          public static void resetStatistics()

Copyright (c) 2014 Eike Stepper (Loehne, Germany) and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v2.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v20.html