Update documentation

gselzer · gselzer · commit ce00177f9759 · 2024-05-06T16:26:13.000-05:00
diff --git a/docs/ops/doc/WritingYourOwnOpPackage.md b/docs/ops/doc/WritingYourOwnOpPackage.md
@@ -276,6 +276,66 @@ class DoubleSizeOp implements Function<double[], Double> {
 
 ```
 
+### Defining Op Progress
+
+By adding the `scijava-progress` module, your Op can define and update its progress, providing user value for long-running Ops. To add progress to your Op, you must add the following steps to your Op:
+* Before any significant computation, add the line `Progress.defineTotal(long elements)` where `elements` is the number of "discrete packets" of computation.
+* At convenient spots within your Op, call `Progress.update()` to denote that one packet of computation has finished. 
+  * **Alternatively**, it may be more convenient or performant to call `Progress.update(long numElements)` to denote `numElements` packets have completed at once.
+
+```java
+/**
+ * A simple summer
+ *
+ * @implNote op names="stats.sum"
+ */
+class DoubleSumOp implements Function<double[], Double> {
+    public Double apply(final double[] inArray) {
+        Progress.defineTotal(inArray.length);
+        double sum = 0;
+        for (double v : inArray) {
+            sum += v;
+            Progress.update();
+        }
+        return i;
+    }
+}
+```
+
+If your Op defines Op dependencies whose progress you'd like to include in your total progress, you can make the following changes.
+* For each Op dependency that you want to track, pass the Hint `"progress.TRACK"` within the `@OpDependency` annotation.
+* Replace `Progress.defineTotal(long elements)` with `Progress.defineTotal(long elements, long subTasks)`, where `subTasks` is the **total** number of times you will invoke Op dependencies annotated with `"progress.TRACK"`.
+
+
+```java
+
+import org.scijava.ops.spi.OpDependency;
+
+/**
+ * A simple mean calculator
+ *
+ * @implNote op names="stats.mean"
+ */
+class DoubleMeanOp implements Function<double[], Double> {
+
+    // This Op will contribute to progress
+    @OpDependency(name="stats.sum", hints={"progress.TRACK"})
+    public Function<double[], Double> sumOp;
+    
+    // This Op will also contribute to progress
+    @OpDependency(name="stats.size", hints={"progress.TRACK"})
+    public Function<double[], Double> sizeOp;
+
+    public Double apply(final double[] inArray) {
+        // There's no significant work here, but we do have 2 subtasks.
+        Progress.defineTotal(0, 2);
+        final Double sum = sumOp.apply(inArray);
+        final Double size = sizeOp.apply(inArray);
+        return sum / size;
+    }
+}
+```
+
 ### Element-wise Ops
 
 Simple pixel-wise operations like addition, inversion, and more can be written on a single pixel (i.e. `RealType`) - therefore, SciJava Ops Image takes care to automagically adapt pixel-wise Ops across a wide variety of image types. If you would like to write a pixel-wise Op, we recommend the following structure.
diff --git a/scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/ReportingProgress.java b/scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/ReportingProgress.java
@@ -33,6 +33,7 @@
 import java.util.List;
 import java.util.function.Function;
 
+import org.scijava.ops.api.Hints;
 import org.scijava.ops.api.OpEnvironment;
 import org.scijava.ops.spi.OpCollection;
 import org.scijava.ops.spi.OpField;
@@ -56,14 +57,13 @@
  * <p>
  * Ops tell the {@link Progress} a few things:
  * <ol>
- * <li>The number of "stages" of computation, including any "subtasks"</li>
- * <li>The number of tasks in each stage</li>
- * <li>When each task has been completed</li>
+ * <li>The number of "elements" in a computation, as well as "subtasks", i.e. dependent Ops</li>
+ * <li>When each "element" has been completed</li>
  * </ol>
  * <p>
- * Note the difference between a "stage" of computation, and a "subtask"
+ * Note the difference between an "element" of computation, and a "subtask"
  * <ul>
- * <li><em>stage</em>s are phases of computation done <b>by the Op</b></li>
+ * <li><em>elements</em>s are pieces of computation done <b>by the Op</b></li>
  * <li><em>subtask</em>s are phases of computation done <b>by other Ops</b></li>
  * </ul>
  * Users are then notified by the progress of Ops by installing
@@ -87,7 +87,7 @@ public class ReportingProgress implements OpCollection {
 
 		// Here, we want to update the progress every time we find a new prime.
 		// We call no Op dependencies, thus the call looks like:
-		Progress.defineTotal(numPrimes, 0);
+		Progress.defineTotal(numPrimes);
 
 		// Progress is defined within the range [0, 1],
 		// where 0 denotes an Op that has not yet started.
@@ -118,6 +118,8 @@ public class ReportingProgress implements OpCollection {
 
 	public static void main(String... args) {
 		OpEnvironment ops = OpEnvironment.build();
+		// To enable Progress Reporting, you must enable the progress tracking hint!
+		ops.setDefaultHints(new Hints("progress.TRACK"));
 
 		// ProgressListeners consume task updates.
 		// This ProgressListener simply logs to standard output, but we could print
diff --git a/scijava-progress/src/main/java/org/scijava/progress/Progress.java b/scijava-progress/src/main/java/org/scijava/progress/Progress.java
@@ -29,11 +29,7 @@
 
 package org.scijava.progress;
 
-import java.util.ArrayDeque;
-import java.util.Collections;
-import java.util.List;
-import java.util.Map;
-import java.util.WeakHashMap;
+import java.util.*;
 import java.util.concurrent.CopyOnWriteArrayList;
 
 /**
@@ -67,13 +63,17 @@ private Progress() {}
 	private static final Map<Object, List<ProgressListener>> progressibleListeners =
 		new WeakHashMap<>();
 
+	/** Singleton NOP task */
+	private static final NOPTask IGNORED = new NOPTask();
+
 	/**
 	 * A record of the progressible {@link Object}s running on each
 	 * {@link Thread}.
 	 */
 	private static final ThreadLocal<ArrayDeque<Task>> progressibleStack =
 		new InheritableThreadLocal<>()
 		{
+			private final Collection<Task> initialContents = Collections.singleton(IGNORED);
 
 			@Override
 			protected ArrayDeque<Task> childValue(ArrayDeque<Task> parentValue) {
@@ -85,7 +85,7 @@ protected ArrayDeque<Task> childValue(ArrayDeque<Task> parentValue) {
 
 			@Override
 			protected ArrayDeque<Task> initialValue() {
-				return new ArrayDeque<>();
+				return new ArrayDeque<>(initialContents);
 			}
 		};
 
@@ -178,7 +178,7 @@ public static void register(final Object progressible,
 		Task t;
 		var deque = progressibleStack.get();
 		var parent = deque.peek();
-		if (parent == null) {
+		if (parent == null || parent == IGNORED) {
 			// completely new execution hierarchy
 			t = new Task(progressible, description);
 		}
@@ -213,7 +213,7 @@ private static void pingListeners(Task task) {
 		for (var l : globalListeners)
 			l.acknowledgeUpdate(task);
 		// Ping parent
-		if (task.parent() != null) {
+		if (task.isSubTask()) {
 			pingListeners(task.parent());
 		}
 	}
@@ -241,11 +241,11 @@ public static void update() {
 	 * Updates the progress of the current {@link Task}, pinging any interested
 	 * {@link ProgressListener}s.
 	 *
-	 * @param numElements the number of elements completed in the current stage.
+	 * @param elements the number of elements completed in the current stage.
 	 * @see Task#update(long)
 	 */
-	public static void update(long numElements) {
-		update(numElements, currentTask());
+	public static void update(long elements) {
+		update(elements, currentTask());
 	}
 
 	/**
@@ -336,6 +336,4 @@ public void defineTotal(final long elements, final long subTasks) {
 
 	}
 
-	private static final NOPTask IGNORED = new NOPTask();
-
 }
