org.eclipse.core.runtime
Class PerformanceStats
java.lang.Object
org.eclipse.core.runtime.PerformanceStats
-
public class PerformanceStats
- extends
Object
PerformanceStats collects and aggregates timing data about events such as
a builder running, an editor opening, etc. This data is collected for the
purpose of performance analysis, and is not intended to be used as
a generic event tracking and notification system.
Each performance event can have an associated maximum acceptable
duration that is specified in the platform debug options file (.options).
Events that take longer than this maximum are logged as errors. Along
with option file entries for each debug event, there are some global debug
options for enabling or disabling performance event gathering and reporting.
See the "org.eclipse.core.runtime/perf*" debug options in the .options file
for the org.eclipse.core.runtime plugin for more details.
A performance event can optionally have additional context information
(
getContext()). This information is only stored in the case
of a performance failure, and can be used to provide further diagnostic
information that can help track down the cause of the failure.
Performance events and performance failures are batched up and periodically
sent to interested performance event listeners.
This class is not intended to be subclassed or instantiated by clients.
-
Since:
- 3.1
|
Field Summary
|
static boolean
|
ENABLED
Constant indicating whether or not tracing is enabled |
|
Method Summary
|
static void
|
addListener
(
PerformanceStats.PerformanceListener listener)
Adds a listener that is notified when performance events occur. |
void
|
addRun
(long elapsed,
String contextName)
Adds an occurrence of this event to the cumulative counters. |
static void
|
clear
()
Discards all known performance event statistics. |
void
|
endRun
()
Stops timing the occurrence of this event that was started by the previous
call to startRun. |
boolean
|
equals
(
Object obj)
|
static
PerformanceStats[]
|
getAllStats
()
Returns all performance event statistics. |
Object
|
getBlame
()
Returns an object that can be used to figure out who caused the event,
or a string describing the cause of the event. |
String
|
getBlameString
()
Returns a string describing the blame for this event. |
String
|
getContext
()
Returns the optional event context, such as the input of an editor, or the target project
of a build event. |
String
|
getEvent
()
Returns the symbolic name of the event that occurred. |
int
|
getRunCount
()
Returns the total number of times this event has occurred. |
long
|
getRunningTime
()
Returns the total execution time in milliseconds for all occurrences
of this event. |
static
PerformanceStats
|
getStats
(
String eventName,
Object blameObject)
Returns the stats object corresponding to the given parameters. |
int
|
hashCode
()
|
static boolean
|
isEnabled
(
String eventName)
Returns whether monitoring of a given performance event is enabled. |
boolean
|
isFailure
()
Returns whether this performance event represents a performance failure. |
static void
|
printStats
()
Prints all statistics to the standard output. |
static void
|
printStats
(
PrintWriter out)
Writes all statistics using the provided writer |
static void
|
removeListener
(
PerformanceStats.PerformanceListener listener)
Removes an event listener. |
static void
|
removeStats
(
String eventName,
Object blameObject)
Removes statistics for a given event and blame |
void
|
reset
()
Resets count and running time for this particular stats event. |
void
|
startRun
()
Starts timing an occurrence of this event. |
void
|
startRun
(
String contextName)
Starts timing an occurrence of this event. |
String
|
toString
()
For debugging purposes only. |
ENABLED
public static final boolean ENABLED
- Constant indicating whether or not tracing is enabled
addListener
public static void addListener(
PerformanceStats.PerformanceListener listener)
- Adds a listener that is notified when performance events occur. If
an equal listener is already installed, it will be replaced.
-
-
Parameters:
-
listener - The listener to be added -
See Also:
-
removeListener(PerformanceStats.PerformanceListener)
clear
public static void clear()
- Discards all known performance event statistics.
-
getAllStats
public static
PerformanceStats[] getAllStats()
- Returns all performance event statistics.
-
-
Returns:
- An array of known performance event statistics. The array
will be empty if there are no recorded statistics.
getStats
public static
PerformanceStats getStats(
String eventName,
Object blameObject)
- Returns the stats object corresponding to the given parameters.
A stats object is created and added to the global list of events if it did not
already exist.
-
-
Parameters:
-
eventName - A symbolic event name. This is usually the name of
the debug option for this event. An example event name from
the org.eclipse.core.resources plugin describing a build event might look like:
"org.eclipse.core.resources/perf/building"" -
blameObject - The blame for the event. This is typically the object
whose code was running when the event occurred. If a blame object cannot
be obtained, a String describing the event should be supplied
isEnabled
public static boolean isEnabled(
String eventName)
- Returns whether monitoring of a given performance event is enabled.
For frequent performance events, the result of this method call should
be cached by the caller to minimize overhead when performance monitoring
is turned off. It is not possible for enablement to change during the life
of this invocation of the platform.
-
-
Parameters:
-
eventName - The name of the event to determine enablement for
-
Returns:
-
trueIf the performance event with the given
name is enabled, and false otherwise.
printStats
public static void printStats()
- Prints all statistics to the standard output.
-
printStats
public static void printStats(
PrintWriter out)
- Writes all statistics using the provided writer
-
-
Parameters:
-
out - The writer to print stats to.
removeListener
public static void removeListener(
PerformanceStats.PerformanceListener listener)
- Removes an event listener. Has no effect if an equal
listener object is not currently registered.
-
-
Parameters:
-
listener - The listener to remove -
See Also:
-
addListener(PerformanceStats.PerformanceListener)
removeStats
public static void removeStats(
String eventName,
Object blameObject)
- Removes statistics for a given event and blame
-
-
Parameters:
-
eventName - The name of the event to remove -
blameObject - The blame for the event to remove
addRun
public void addRun(long elapsed,
String contextName)
- Adds an occurrence of this event to the cumulative counters. This method
can be used as an alternative to
startRun and endRun
for clients that want to track the context and execution time separately.
-
-
Parameters:
-
elapsed - The elapsed time of the new occurrence in milliseconds -
contextName - The context for the event to return, or null.
The context optionally provides extra information about an event, such as the
name of a project being built, or the input of an editor being opened.
endRun
public void endRun()
- Stops timing the occurrence of this event that was started by the previous
call to
startRun. The event is automatically added to
the cumulative counters for this event and listeners are notified.
Note that this facility guards itself against runs that start but fail to stop,
so it is not necessary to call this method from a finally block. Tracking
performance of failure cases is generally not of interest.
-
-
See Also:
-
startRun()
equals
public boolean equals(
Object obj)
-
-
Overrides:
-
equals
in class
Object
-
getBlame
public
Object getBlame()
- Returns an object that can be used to figure out who caused the event,
or a string describing the cause of the event.
-
-
Returns:
- The blame for this event
getBlameString
public
String getBlameString()
- Returns a string describing the blame for this event.
-
-
Returns:
- A string describing the blame.
getContext
public
String getContext()
- Returns the optional event context, such as the input of an editor, or the target project
of a build event.
-
-
Returns:
- The context, or
null if there is none
getEvent
public
String getEvent()
- Returns the symbolic name of the event that occurred.
-
-
Returns:
- The name of the event.
getRunCount
public int getRunCount()
- Returns the total number of times this event has occurred.
-
-
Returns:
- The number of occurrences of this event.
getRunningTime
public long getRunningTime()
- Returns the total execution time in milliseconds for all occurrences
of this event.
-
-
Returns:
- The total running time in milliseconds.
hashCode
public int hashCode()
-
-
Overrides:
-
hashCode
in class
Object
-
isFailure
public boolean isFailure()
- Returns whether this performance event represents a performance failure.
-
-
Returns:
-
true if this is a performance failure, and
false otherwise.
reset
public void reset()
- Resets count and running time for this particular stats event.
-
startRun
public void startRun()
- Starts timing an occurrence of this event. This is a convenience method,
fully equivalent to
startRun(null).
-
startRun
public void startRun(
String contextName)
- Starts timing an occurrence of this event. The event should be stopped
by a subsequent call to
endRun.
-
-
Parameters:
-
contextName - The context for the event to return, or null.
The context optionally provides extra information about an event, such as the
name of a project being built, or the input of an editor being opened. -
See Also:
-
endRun()
toString
public
String toString()
- For debugging purposes only.
-
-
Overrides:
-
toString
in class
Object
-
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.
