Bug 441015 - Provide out-of-the-box monitoring of UI delays

Update comments for StackSample and UiFreezeEvent.

Change-Id: Id10f9bdcecb906b9668bfb7bae57ad0fbbc9da04
Signed-off-by: Terry Parker <tparker@google.com>

2 files changed, 31 insertions, 11 deletions

diff --git a/bundles/org.eclipse.ui.monitoring/src/org/eclipse/ui/monitoring/StackSample.java b/bundles/org.eclipse.ui.monitoring/src/org/eclipse/ui/monitoring/StackSample.java
index 1944d035e54..f96e2e3207a 100644
--- a/bundles/org.eclipse.ui.monitoring/src/org/eclipse/ui/monitoring/StackSample.java
+++ b/bundles/org.eclipse.ui.monitoring/src/org/eclipse/ui/monitoring/StackSample.java
@@ -22,20 +22,29 @@ public class StackSample {
 	private final long timestamp;
 	private final ThreadInfo[] traces;
 
+	/**
+	 * Creates a StackSample.
+	 *
+	 * @param timestamp time in milliseconds since January 1, 1970 UTC when the thread stacks
+	 *     were sampled
+	 * @param traces thread information for either all threads or just the display thread,
+	 *     depending on the value of the {@link PreferenceConstants#DUMP_ALL_THREADS} preference
+	 */
 	public StackSample(long timestamp, ThreadInfo[] traces) {
 		this.timestamp = timestamp;
 		this.traces = traces;
 	}
 
 	/**
-	 * Returns the time stamp for this {@code StackSample}.
+	 * Returns the time stamp in milliseconds since January 1, 1970 UTC for this
+	 * {@code StackSample}.
 	 */
 	public long getTimestamp() {
 		return timestamp;
 	}
 
 	/**
-	 * Returns an array of {@code ThreadInfo} for this {@code StackSample}. The display thread is
+	 * Returns an array of {@code ThreadInfo}s for this {@code StackSample}. The display thread is
 	 * always the first in the array.
 	 */
 	public ThreadInfo[] getStackTraces() {
diff --git a/bundles/org.eclipse.ui.monitoring/src/org/eclipse/ui/monitoring/UiFreezeEvent.java b/bundles/org.eclipse.ui.monitoring/src/org/eclipse/ui/monitoring/UiFreezeEvent.java
index 447355a59a3..276b4fbcc67 100644
--- a/bundles/org.eclipse.ui.monitoring/src/org/eclipse/ui/monitoring/UiFreezeEvent.java
+++ b/bundles/org.eclipse.ui.monitoring/src/org/eclipse/ui/monitoring/UiFreezeEvent.java
@@ -20,25 +20,35 @@ public class UiFreezeEvent {
 	private final long startTimestamp;
 	private final long totalDuration;
 	private final StackSample[] stackTraceSamples;
-	private final boolean isRunning;
+	private final boolean isStillRunning;
 
-	public UiFreezeEvent(long startTime, long totalTime, StackSample[] samples,
+	/**
+	 * Creates a UiFreezeEvent.
+	 *
+	 * @param startTime initial dispatch time for the event in milliseconds since January 1,
+	 *     1970 UTC
+	 * @param duration duration of the event in milliseconds
+	 * @param samples array of {@link StackSample}s containing thread information
+	 * @param stillRunning whether or not the event was still running when this UiFreezeEvent
+	 *     was created. If {@code true}, this UiFreezeEvent may indicate a deadlock.
+	 */
+	public UiFreezeEvent(long startTime, long duration, StackSample[] samples,
 			boolean stillRunning) {
 		this.startTimestamp = startTime;
 		this.stackTraceSamples = samples;
-		this.totalDuration = totalTime;
-		this.isRunning = stillRunning;
+		this.totalDuration = duration;
+		this.isStillRunning = stillRunning;
 	}
 
 	/**
-	 * Returns the time when the UI thread froze.
+	 * Returns the time when the UI thread froze, in milliseconds since January 1, 1970 UTC.
 	 */
 	public long getStartTimestamp() {
 		return startTimestamp;
 	}
 
 	/**
-	 * Returns the total amount of time the UI thread remained frozen.
+	 * Returns the total amount of time in milliseconds that the UI thread remained frozen.
 	 */
 	public long getTotalDuration() {
 		return totalDuration;
@@ -52,10 +62,11 @@ public class UiFreezeEvent {
 	}
 
 	/**
-	 * Returns {@code true} if this event is still running.
+	 * Returns {@code true} if this event was still running at the time the event was logged,
+	 * which can happen for deadlocks.
 	 */
 	public boolean isStillRunning() {
-		return isRunning;
+		return isStillRunning;
 	}
 
 	/** For debugging only. */
@@ -64,7 +75,7 @@ public class UiFreezeEvent {
 		StringBuilder buf = new StringBuilder();
 		buf.append("Freeze started at ");
 		buf.append(startTimestamp);
-		if (isRunning) {
+		if (isStillRunning) {
 			buf.append(" still ongoing after ");
 		} else {
 			buf.append(" lasted ");