Skip to content

Commit 94f6a42

Browse files
authored
Merge pull request #80 from scijava/scijava/scijava-ops-engine/global-progress
Create API for global progress listeners
2 parents 4ef7e39 + be67962 commit 94f6a42

10 files changed

Lines changed: 367 additions & 166 deletions

File tree

‎imagej/imagej-ops2-tutorial/src/main/java/net/imagej/ops2/tutorial/ReportingProgress.java‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@
3737
import org.scijava.ops.spi.OpField;
3838
import org.scijava.progress.Progress;
3939
import org.scijava.progress.ProgressListener;
40+
import org.scijava.progress.StandardOutputProgressLogger;
4041
import org.scijava.types.Nil;
4142

4243
/**
@@ -116,21 +117,23 @@ public static void main(String... args) {
116117
OpEnvironment ops = OpEnvironment.getEnvironment();
117118

118119
// ProgressListeners consume task updates.
119-
// This ProgressListener simply prints out the status of the Op
120-
// to the console, but we could print out something else,
121-
// or pass this information somewhere else.
122-
ProgressListener l = //
123-
task -> System.out.printf("Op progress: %.2f\n", task.progress());
120+
// This ProgressListener simply logs to standard output, but we could print
121+
// out something else, or pass this information somewhere else.
122+
ProgressListener l = new StandardOutputProgressLogger();
123+
// To listen to Op progress updates, the ProgressListener must be registered
124+
// through the Progress API. To listen to all Op executions, use the
125+
// following call:
126+
Progress.addGlobalListener(l);
127+
// If listening to every Op would be overwhelming, the Progress API also
128+
// allows ProgressListeners to be registered for a specific Op, using the
129+
// following call:
130+
// Progress.addListener(op, l);
124131

125132
// Get the function.
126133
var op = ops.unary("tutorial.long.op") //
127134
.inType(Integer.class) //
128135
.outType(new Nil<List<Long>>() {}) //
129136
.function();
130-
// Listening to every Op would be overwhelming.
131-
// Ops must be deliberately linked to a ProgressListener through the
132-
// Progress API.
133-
Progress.addListener(op, l);
134137

135138
// When we apply the Op, we will automatically print the progress out to
136139
// the console, thanks to our ProgressListener above.

‎scijava/scijava-ops-api/src/main/java/org/scijava/ops/api/OpInstance.java‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,4 +91,9 @@ public Type getType() {
9191
return reifiedType;
9292
}
9393

94+
@Override
95+
public String toString() {
96+
return infoTree().info().implementationName();
97+
}
98+
9499
}

‎scijava/scijava-ops-engine/src/main/java/org/scijava/ops/engine/matcher/impl/AbstractRichOp.java‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,4 +100,9 @@ public void recordExecutions(boolean record) {
100100
this.record = record;
101101
}
102102

103+
@Override
104+
public String toString() {
105+
return instance().toString();
106+
}
107+
103108
}

‎scijava/scijava-progress/pom.xml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,6 @@
105105
<allowedDuplicateClasses>${scijava-progress.allowedDuplicateClasses}</allowedDuplicateClasses>
106106
</properties>
107107
<dependencies>
108-
<!-- SciJava dependencies -->
109108
<!-- Test scope dependencies -->
110109
<dependency>
111110
<groupId>org.junit.jupiter</groupId>

‎scijava/scijava-progress/src/main/java/org/scijava/progress/Progress.java‎

Lines changed: 63 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,13 @@
4444
*/
4545
public final class Progress {
4646

47+
/**
48+
* A record of all listeners interested in the progress of all Object
49+
* executions
50+
*/
51+
private static final List<ProgressListener> globalListeners =
52+
new ArrayList<>();
53+
4754
/**
4855
* A record of all listeners interested in the progress of a given Object's
4956
* executions
@@ -75,6 +82,19 @@ protected ArrayDeque<ProgressibleObject> initialValue() {
7582
}
7683
};
7784

85+
/**
86+
* Records {@link ProgressListener} {@code l} as a callback for all
87+
* progressible {@link Object}s
88+
*
89+
* @param l a {@link ProgressListener} that would like to know about the
90+
* progress of {@code progressible} {@link Object}s
91+
*/
92+
public static void addGlobalListener(ProgressListener l) {
93+
if (!globalListeners.contains(l)) {
94+
globalListeners.add(l);
95+
}
96+
}
97+
7898
/**
7999
* Records {@link ProgressListener} {@code l} as a callback for progressible
80100
* {@link Object} {@code progressible}
@@ -106,41 +126,62 @@ private static synchronized void createListenerList(Object progressible) {
106126

107127
/**
108128
* Completes the current task on this {@link Thread}'s execution hierarchy,
109-
* removing it in the process. This method also takaes care to ping relevant {@link ProgressListener}s.
129+
* removing it in the process. This method also takaes care to ping relevant
130+
* {@link ProgressListener}s.
110131
*
111132
* @see Task#complete()
112133
*/
113134
public static void complete() {
114135
// update completed task
115136
ProgressibleObject completed = progressibleStack.get().pop();
116-
completed.task().complete();
117-
// ping relevant listeners
118-
pingListeners(completed);
119-
if (progressibleStack.get().peek() != null) {
120-
pingListeners(progressibleStack.get().peek());
137+
if (!completed.task().isComplete()) {
138+
completed.task().complete();
139+
// ping relevant listeners
140+
pingListeners(completed);
141+
if (progressibleStack.get().peek() != null) {
142+
pingListeners(progressibleStack.get().peek());
143+
}
121144
}
122145
}
123146

147+
/**
148+
* Creates a new {@link Task} for {@code progressible}. This method makes the
149+
* assumption that {@code progressible} is responsible for any calls to
150+
* {@link Progress}' progress-reporting API between the time this method is
151+
* called and the time when {@link Progress#complete()} is called.
152+
*
153+
* @param progressible an {@link Object} that would like to report its
154+
* progress.
155+
*/
156+
public static void register(final Object progressible) {
157+
register(progressible, progressible.toString());
158+
}
159+
124160
/**
125161
* Creates a new {@link Task} for {@code progressible}. This method makes the
126162
* assumption that {@code progressible} is responsible for any calls to
127163
* {@link Progress}' progress-reporting API between the time this method is
128164
* called and the time when {@link Progress#complete()} is called.
129165
*
130-
* @param progressible an {@link Object} that would like to report its progress.
166+
* @param progressible an {@link Object} that would like to report its
167+
* progress.
168+
* @param description a {@link String} describing {@code progressible}
131169
*/
132-
public static void register(Object progressible) {
170+
public static void register(final Object progressible,
171+
final String description)
172+
{
133173
Task t;
134-
if (progressibleStack.get().size() == 0) {
174+
var deque = progressibleStack.get();
175+
var parent = deque.peek();
176+
if (parent == null) {
135177
// completely new execution hierarchy
136-
t = new Task();
178+
t = new Task(description);
137179
}
138180
else {
139181
// part of an existing execution hierarchy
140-
ProgressibleObject parent = progressibleStack.get().peek();
141-
t = parent.task().createSubtask();
182+
t = parent.task().createSubtask(description);
142183
}
143-
progressibleStack.get().push(new ProgressibleObject(progressible, t));
184+
deque.push(new ProgressibleObject(progressible, t));
144185
}
145186

146187
/**
@@ -150,11 +191,16 @@ public static void register(Object progressible) {
150191
* @param o an {@link Object} reporting its progress.
151192
*/
152193
private static void pingListeners(ProgressibleObject o) {
194+
// Ping object-specific listeners
153195
List<ProgressListener> list = progressibleListeners.getOrDefault(o.object(),
154196
Collections.emptyList());
155197
synchronized (list) {
156198
list.forEach(l -> l.acknowledgeUpdate(o.task()));
157199
}
200+
// Ping global listeners
201+
synchronized (globalListeners) {
202+
globalListeners.forEach(l -> l.acknowledgeUpdate(o.task()));
203+
}
158204
}
159205

160206
/**
@@ -202,18 +248,18 @@ public static void setStatus(String status) {
202248
/**
203249
* Defines the total progress of the current {@link Task}
204250
*
205-
* @see Task#defineTotalProgress(int)
251+
* @see Task#defineTotalProgress(long)
206252
*/
207-
public static void defineTotalProgress(int numStages) {
253+
public static void defineTotalProgress(long numStages) {
208254
currentTask().defineTotalProgress(numStages);
209255
}
210256

211257
/**
212258
* Defines the total progress of the current {@link Task}
213259
*
214-
* @see Task#defineTotalProgress(int, int)
260+
* @see Task#defineTotalProgress(long, long)
215261
*/
216-
public static void defineTotalProgress(int numStages, int numSubTasks) {
262+
public static void defineTotalProgress(long numStages, long numSubTasks) {
217263
currentTask().defineTotalProgress(numStages, numSubTasks);
218264
}
219265

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
2+
package org.scijava.progress;
3+
4+
/**
5+
* Simple {@link ProgressListener} logging updates to standard output.
6+
*
7+
* @author Gabriel Selzer
8+
*/
9+
public class StandardOutputProgressLogger implements ProgressListener {
10+
11+
@Override
12+
public void acknowledgeUpdate(Task task) {
13+
if (task.isComplete()) {
14+
System.out.printf("Progress of %s: Complete\n", task.description());
15+
}
16+
else {
17+
System.out.printf( //
18+
"Progress of %s: %.2f\n", //
19+
task.description(), //
20+
task.progress() //
21+
);
22+
}
23+
}
24+
}

‎scijava/scijava-progress/src/main/java/org/scijava/progress/Task.java‎

Lines changed: 32 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@
3535

3636
/**
3737
* Keeps track of progress associated with an execution of progressable code.
38-
* {@Link Task}s should <b>not</b> be updated by the code itself; it should be
38+
* {@link Task}s should <b>not</b> be updated by the code itself; it should be
3939
* update via {@link Progress#update()}.
4040
*
4141
* @author Gabriel Selzer
@@ -48,7 +48,7 @@ public class Task {
4848
private final Task parent;
4949

5050
/** Subtasks created by this task */
51-
private Set<Task> subTasks = new HashSet<>();
51+
private final Set<Task> subTasks = new HashSet<>();
5252

5353
/** Designates task completion */
5454
private boolean completed = false;
@@ -60,34 +60,40 @@ public class Task {
6060
private long numSubTasks = 0;
6161

6262
/** Progress in current stage */
63-
private AtomicLong current = new AtomicLong(0);
63+
private final AtomicLong current = new AtomicLong(0);
6464

6565
/** Maximum of current stage */
66-
private AtomicLong max = new AtomicLong(1);
66+
private final AtomicLong max = new AtomicLong(1);
6767

6868
/** Number of within-task stages completed */
69-
private AtomicLong stagesCompleted = new AtomicLong(0);
69+
private final AtomicLong stagesCompleted = new AtomicLong(0);
7070

7171
/** Number of subtasks completed */
72-
private AtomicLong subTasksCompleted = new AtomicLong(0);
72+
private final AtomicLong subTasksCompleted = new AtomicLong(0);
7373

7474
/**
75-
* True iff a call to {@link Task#defineTotalProgress(int, int)} has been made
75+
* True iff a call to {@link Task#defineTotalProgress(long, long)} has been
76+
* made
7677
*/
7778
private boolean tasksDefined = false;
7879

7980
/** True iff {@link Task#max} has been defined for the current stage */
8081
private boolean updateDefined = false;
8182

83+
/** String identifying the task */
84+
private final String description;
85+
8286
/** Computation status as defined by the task */
8387
private String status = "Executing...";
8488

85-
public Task() {
89+
public Task(final String description) {
8690
this.parent = null;
91+
this.description = description;
8792
}
8893

89-
public Task(final Task parent) {
94+
public Task(final Task parent, final String description) {
9095
this.parent = parent;
96+
this.description = description;
9197
}
9298

9399
/**
@@ -111,8 +117,8 @@ public void complete() {
111117
*
112118
* @return the subtask.
113119
*/
114-
public synchronized Task createSubtask() {
115-
final Task sub = new Task(this);
120+
public synchronized Task createSubtask(String description) {
121+
final Task sub = new Task(this, description);
116122
subTasks.add(sub);
117123
return sub;
118124
}
@@ -124,11 +130,11 @@ public synchronized Task createSubtask() {
124130
* {@link Task#progress()} are called, as otherwise total progress cannot be
125131
* defined.
126132
* <p>
127-
* Under the hood, this method calls {@link #defineTotalProgress(int, int)}
133+
* Under the hood, this method calls {@link #defineTotalProgress(long, long)}
128134
*
129135
* @param totalStages the number of computation stages within the task
130136
*/
131-
public void defineTotalProgress(final int totalStages) {
137+
public void defineTotalProgress(final long totalStages) {
132138
defineTotalProgress(totalStages, 0);
133139
}
134140

@@ -144,8 +150,8 @@ public void defineTotalProgress(final int totalStages) {
144150
* within the task. This <b>is not</b> the same as the number of
145151
* subtasks used (as one subtask may run multiple times).
146152
*/
147-
public void defineTotalProgress(final int totalStages,
148-
final int totalSubTasks)
153+
public void defineTotalProgress(final long totalStages,
154+
final long totalSubTasks)
149155
{
150156
this.numStages = totalStages;
151157
this.numSubTasks = totalSubTasks;
@@ -164,8 +170,8 @@ public boolean isComplete() {
164170
/**
165171
* Calculates and returns the progress of the associated progressible
166172
* {@link Object}. If the total progress is defined using
167-
* {@link Task#defineTotalProgress(int, int)}, then this method will return a
168-
* {@code double} within the range [0, 1]. If the progress is <b>not</b>
173+
* {@link Task#defineTotalProgress(long, long)}, then this method will return
174+
* a {@code double} within the range [0, 1]. If the progress is <b>not</b>
169175
* defined, then this task will return {@code 0} until {@link #complete()} is
170176
* called; after that call this method will return {@code 1.}.
171177
*
@@ -180,15 +186,6 @@ public double progress() {
180186
return totalCompletion / (numStages + numSubTasks);
181187
}
182188

183-
/**
184-
* Returns {@code true} iff progress has been defined
185-
*
186-
* @return {@code true} iff progress has been defined
187-
*/
188-
public boolean progressDefined() {
189-
return tasksDefined;
190-
}
191-
192189
/**
193190
* Iff {@code task} was a task generated by this {@link Task}, then we update
194191
* progress based on its completion.
@@ -206,8 +203,6 @@ private void resetStage() {
206203
current.set(0);
207204
stagesCompleted.incrementAndGet();
208205
this.updateDefined = false;
209-
if (stagesCompleted.longValue() == numStages && subTasksCompleted
210-
.longValue() == numSubTasks) completed = true;
211206
}
212207

213208
/**
@@ -241,6 +236,15 @@ public String status() {
241236
return status;
242237
}
243238

239+
/**
240+
* The id of the progressible {@link Object}
241+
*
242+
* @return the id
243+
*/
244+
public String description() {
245+
return description;
246+
}
247+
244248
/**
245249
* Used by a progressible {@link Object}, through {@link Progress} to
246250
* increment progress

0 commit comments

Comments
 (0)