Document and generalize PromiseCombiner

Motivation:

`PromiseCombiner` is really handy, but it's not obvious how to use it from its existing documentation/method signatures.

Modification:

- Added javadoc comments to explain the theory of operation of `PromiseCombiner`.
- Generalized `PromiseCombiner` to work with `Futures` so it's clearer that the things for which it's listening won't be modified.

Result:

`PromiseCombiner` is easier to understand.
This commit is contained in:
Jon Chambers 2016-12-18 18:48:43 -05:00 committed by Norman Maurer
parent 16ddf460a6
commit 7c630feefc

View File

@ -17,6 +17,18 @@ package io.netty.util.concurrent;
import io.netty.util.internal.ObjectUtil; import io.netty.util.internal.ObjectUtil;
/**
* <p>A promise combiner monitors the outcome of a number of discrete futures, then notifies a final, aggregate promise
* when all of the combined futures are finished. The aggregate promise will succeed if and only if all of the combined
* futures succeed. If any of the combined futures fail, the aggregate promise will fail. The cause failure for the
* aggregate promise will be the failure for one of the failed combined futures; if more than one of the combined
* futures fails, exactly which cause of failure will be assigned to the aggregate promise is undefined.</p>
*
* <p>Callers may populate a promise combiner with any number of futures to be combined via the
* {@link PromiseCombiner#add(Future)} and {@link PromiseCombiner#addAll(Future[])} methods. When all futures to be
* combined have been added, callers must provide an aggregate promise to be notified when all combined promises have
* finished via the {@link PromiseCombiner#finish(Promise)} method.</p>
*/
public final class PromiseCombiner { public final class PromiseCombiner {
private int expectedCount; private int expectedCount;
private int doneCount; private int doneCount;
@ -36,22 +48,43 @@ public final class PromiseCombiner {
} }
}; };
/**
* Adds a new future to be combined. New futures may be added until an aggregate promise is added via the
* {@link PromiseCombiner#finish(Promise)} method has been called.
*
* @param future the future to add to this promise combiner
*/
@SuppressWarnings({ "unchecked", "rawtypes" }) @SuppressWarnings({ "unchecked", "rawtypes" })
public void add(Promise promise) { public void add(Future future) {
checkAddAllowed(); checkAddAllowed();
++expectedCount; ++expectedCount;
promise.addListener(listener); future.addListener(listener);
} }
/**
* Adds new futures to be combined. New futures may be added until an aggregate promise is added via the
* {@link PromiseCombiner#finish(Promise)} method has been called.
*
* @param futures the futures to add to this promise combiner
*/
@SuppressWarnings({ "unchecked", "rawtypes" }) @SuppressWarnings({ "unchecked", "rawtypes" })
public void addAll(Promise... promises) { public void addAll(Future... futures) {
checkAddAllowed(); for (Future future : futures) {
expectedCount += promises.length; this.add(future);
for (Promise promise : promises) {
promise.addListener(listener);
} }
} }
/**
* <p>Sets the promise to be notified when all combined futures have finished. If all combined futures succeed,
* then the aggregate promise will succeed. If one or more combined futures fails, then the aggregate promise will
* fail with the cause of one of the failed futures. If more than one combined future fails, then exactly which
* failure will be assigned to the aggregate promise is undefined.</p>
*
* <p>After this method is called, no more futures may be added via the {@link PromiseCombiner#add(Future)} or
* {@link PromiseCombiner#addAll(Future[])} methods.</p>
*
* @param aggregatePromise the promise to notify when all combined futures have finished
*/
public void finish(Promise<Void> aggregatePromise) { public void finish(Promise<Void> aggregatePromise) {
if (doneAdding) { if (doneAdding) {
throw new IllegalStateException("Already finished"); throw new IllegalStateException("Already finished");