The scenarios below are applicable to any async expressions.
Note that for Collections⇗, results are automatically collected using AsyncMode.CancellAll internally.
async(
asyncMode = <ANY>,
job1 = asyncJob{...},
job2 = asyncJob{...},
job3 = asyncJob{...},
job4 = asyncJob{...},
job5 = asyncJob{...},
) { ok, r1, r2, r3, r4, r5 ->
:
}
No Failures
In a perfect scenario, all the AsyncJobs succeed:
AsyncJobs can finish at any time, in any order.
If there are no errors, then all results are AsyncResult.Completed.Success.
For example, when triggering 5 AsyncJobs:
job4 finishes first.
job5 finishes second.
job3 finishes third.
job1 finishes fourth.
job2 finishes last.
The results will be collected as follows:
ok → true
r1 → AsyncResult.Completed.Success
r2 → AsyncResult.Completed.Success
r3 → AsyncResult.Completed.Success
r4 → AsyncResult.Completed.Success
r5 → AsyncResult.Completed.Success
async(
asyncMode = AsyncMode.CancelNone,
job1 = asyncJob{...},
job2 = asyncJob{...},
job3 = asyncJob{...},
job4 = asyncJob{...},
job5 = asyncJob{...},
) { ok, r1, r2, r3, r4, r5 ->
:
}
AsyncMode.CancelNone
If a failure is detected, CancelNone mode does not cancel any pending AsyncJobs:
This is the default asyncMode when using any async expression - except Collections⇗.
AsyncJobs that were completed will not be affected.
Pending AsyncJobs will continue to be executed until finished.
Results can be either Success or Failure, since no job-cancellation will take place - except if there's a timeout on the caller's scope hierarchy.
For example, when triggering 5 AsyncJobs:
job4 and job5 finish successfully.
job3 fails while job1 and job2 are executed.
job1 fails while job2 is executed.
job2 finishes successfully.
The results will be collected as follows:
ok → false
r1 → AsyncResult.Completed.Failure
r2 → AsyncResult.Completed.Success
r3 → AsyncResult.Completed.Failure
r4 → AsyncResult.Completed.Success
r5 → AsyncResult.Completed.Success
async(
asyncMode = AsyncMode.CancelFirst,
job1 = asyncJob{...},
job2 = asyncJob{...},
job3 = asyncJob{...},
job4 = asyncJob{...},
job5 = asyncJob{...},
) { ok, r1, r2, r3, r4, r5 ->
:
}
AsyncMode.CancelFirst
If a failure is detected, CancelFirst mode will cancel any pending AsyncJobs:
AsyncJobs that were completed will not be affected.
The first failing AsyncJob will be a Failure.
Pending AsyncJobs will be cancelled.
Results can be Success, Failure, or Cancelled.
Use this mode as a fail-fast approach → early termination.
For example, when triggering 5 AsyncJobs:
job4 and job5 finish successfully.
job3 fails while job1 and job2 are executed.
job1 and job2 are cancelled.
The results will be collected as follows:
ok → false
r1 → AsyncResult.Cancelled
r2 → AsyncResult.Cancelled
r3 → AsyncResult.Completed.Failure
r4 → AsyncResult.Completed.Success
r5 → AsyncResult.Completed.Success
async(
asyncMode = AsyncMode.CancelAll,
job1 = asyncJob{...},
job2 = asyncJob{...},
job3 = asyncJob{...},
job4 = asyncJob{...},
job5 = asyncJob{...},
) { ok, r1, r2, r3, r4, r5 ->
:
}
AsyncMode.CancelAll
If a failure is detected, cancel all AsyncJobs:
This mode enforces strict failure propagation:
First AsyncJob causing the error will be a Failure.
AsyncJobs that were completed will be marked as Cancelled.
Pending AsyncJobs will be cancelled.
All results are Cancelled, except for the one causing the Failure.
This mode could be used on all-or-nothing scenarios. Of course, results that were a Success are discarded - in some situations this may be acceptable.
For example, when triggering 5 AsyncJobs:
job4 and job5 finish successfully.
job3 fails while job1 and job2 are executed.
job1 and job2 are cancelled.
job4 and job5 are marked as cancelled.
The results will be collected as follows:
ok → false
r1 → AsyncResult.Cancelled
r2 → AsyncResult.Cancelled
r3 → AsyncResult.Completed.Failure
r4 → AsyncResult.Cancelled
r5 → AsyncResult.Cancelled
Parallel Mode
All async expressions allow to specify a parallel parameter → by default, it is true.
If set to false, it will force an AsyncScope to execute all AsyncJobs sequentially, in the same order they were added.
The specified AsyncMode will be enforced:
AsyncMode.CancelNone → All AsyncJobs will be executed, reporting their AsyncResults as expected (Success, Failure).
AsyncMode.CancelFirst → AsyncJobs will be executed one by one, stopping on the first error. AsyncResults will be Success until the first Failure. For all non-executed AsyncJobs, results will be Cancelled.
AsyncMode.CancelAll → AsyncJobs will be executed one by one, stopping on the first error. All AsyncResults will be Cancelled except for the Failure.
This parallel parameter has been added only to simplify development and troubleshooting.
Actual production releases should not include this parameter, leaving the default setting parallel=true.