Queue AwaitAll Method Counters

[DK96-OS]

The AwaitAll method of the CoroutineQueue can be used to wait for the queue to finish all active tasks, and clear them in queue order.

This is usually only recommended if the active tasks don't have a useful deferred return value, but want to allow them to finish. If it does not matter if the tasks finish, the cancel task is available.

Take a moment to consider the potential use cases where awaitAll is preferred over cancel ...

Enhancements

1. Feedback from the method (a return value), such as the number of tasks that were waited on would be beneficial. This allows the number of discarded results to be logged, or compared with an expected value.

2. Limiting the maximum number of tasks that will be waited for (with a method parameter). The Queue structure makes it easy to predict the order of tasks.

Finished Task Counter

The number of tasks that were completed during the awaitAll call can easily be measured and returned.

Await Limit Parameter

The maximum number of tasks to wait for during an awaitAll call can be added to the method declaration.

Await All Example

Suppose there are initially 5 tasks that require completion, waiting in the queue. Suddenly 5 more tasks are added, which have important deferred values that invalidate the inital 5 tasks.

Since the results from the inital 5 are better off being ignored, but need to complete, you use awaitAll.

Before Await Limit Parameter

You have to call awaitAll before adding the new 5 tasks to the Queue. Alternatively, you can call awaitNext 5 times.

After Await Limit Parameter

You know the initial 5 are the only tasks in the Queue, and they are at the front of the Queue.

You can add the 5 new tasks to the Queue at any time, allowing them to start sooner.

You could do additional work at this point, or make the call to awaitAll with a limit of 5.

[DK96-OS]

Backwards Compatibility

Treat all Integers with a value less than 1 as an indication that the original await ALL behaviour is desired.

Use 0 as the default parameter for the method.

[DK96-OS]

The Cancel method can receive these same enhancements.

Although, at minimum it can return the number of tasks cancelled. This has been done in #8. Providing a limit on the number of tasks to cancel is now a desirable feature, but it has lower priority than the currently scheduled features.