Parallel¶
Concurrent branches¶
Parallel executes multiple operations concurrently. It manages concurrency, collects results as branches complete, and checkpoints the outcome.
Each branch runs in its own child context. The default nested mode checkpoints that context and its result. Flat mode omits the per-branch context checkpoint to reduce operation overhead.
Use parallel to execute independent tasks concurrently. Use map instead to execute the same operation concurrently for each item in a collection.
import {
BatchResult,
DurableContext,
withDurableExecution,
} from "@aws/durable-execution-sdk-js";
export const handler = withDurableExecution(
async (event: any, context: DurableContext): Promise<string[]> => {
const result: BatchResult<string> = await context.parallel("check-services", [
async (ctx) => ctx.step("check-inventory", async () => "inventory ok"),
async (ctx) => ctx.step("check-payment", async () => "payment ok"),
async (ctx) => ctx.step("check-shipping", async () => "shipping ok"),
]);
return result.getResults();
},
);
from aws_durable_execution_sdk_python import (
BatchResult,
DurableContext,
durable_execution,
)
def check_inventory(ctx: DurableContext) -> str:
return ctx.step(lambda _: "inventory ok", name="check-inventory")
def check_payment(ctx: DurableContext) -> str:
return ctx.step(lambda _: "payment ok", name="check-payment")
def check_shipping(ctx: DurableContext) -> str:
return ctx.step(lambda _: "shipping ok", name="check-shipping")
@durable_execution
def handler(event: dict, context: DurableContext) -> list[str]:
result: BatchResult[str] = context.parallel(
[check_inventory, check_payment, check_shipping],
name="check-services",
)
return result.get_results()
import java.util.List;
import software.amazon.lambda.durable.DurableContext;
import software.amazon.lambda.durable.DurableHandler;
import software.amazon.lambda.durable.model.ParallelResult;
public class SimpleParallel extends DurableHandler<Void, ParallelResult> {
@Override
public ParallelResult handleRequest(Void input, DurableContext context) {
try (var parallel = context.parallel("check-services")) {
parallel.branch("check-inventory", String.class,
ctx -> ctx.step("inventory", String.class, s -> "inventory ok"));
parallel.branch("check-payment", String.class,
ctx -> ctx.step("payment", String.class, s -> "payment ok"));
parallel.branch("check-shipping", String.class,
ctx -> ctx.step("shipping", String.class, s -> "shipping ok"));
return parallel.get();
}
}
}
// Package main runs independent branches concurrently with Parallel and
// returns their results in input order.
package main
import "github.com/aws/aws-durable-execution-sdk-go/durable"
func handler(ctx durable.Context, _ any) ([]string, error) {
result, err := durable.Parallel(ctx, "check-services", []durable.Branch[string]{
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "check-inventory", func(durable.StepContext) (string, error) {
return "inventory ok", nil
})
}},
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "check-payment", func(durable.StepContext) (string, error) {
return "payment ok", nil
})
}},
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "check-shipping", func(durable.StepContext) (string, error) {
return "shipping ok", nil
})
}},
})
if err != nil {
return nil, err
}
return result.Results(), nil
}
func main() { durable.Start(handler) }
All branches must return the same type. For branches of different result
types, use ParallelMixed.
use aws_durable_execution_sdk as durable;
async fn handler(
_event: serde_json::Value,
ctx: durable::DurableContext,
) -> Result<Vec<String>, durable::BoxError> {
let results = ctx
.parallel([
durable::Branch::unnamed(|ctx| async move {
Ok(ctx
.step(|_| async { Ok("inventory ok".to_owned()) })
.name("check-inventory")
.await?)
}),
durable::Branch::unnamed(|ctx| async move {
Ok(ctx
.step(|_| async { Ok("payment ok".to_owned()) })
.name("check-payment")
.await?)
}),
durable::Branch::unnamed(|ctx| async move {
Ok(ctx
.step(|_| async { Ok("shipping ok".to_owned()) })
.name("check-shipping")
.await?)
}),
])
.name("check-services")
.await?;
Ok(results)
}
#[tokio::main]
async fn main() -> Result<(), lambda_runtime::Error> {
durable::init_default_subscriber()?;
durable::run(handler).await
}
Each branch is a durable::Branch<O>, and all branches return the same type O.
For branches of different result types, use
parallel_mixed.
using Amazon.Lambda.Core;
using Amazon.Lambda.DurableExecution;
public class SimpleParallelExample
{
public Task<DurableExecutionInvocationOutput> Handler(
DurableExecutionInvocationInput input, ILambdaContext context)
=> DurableFunction.WrapAsync<object, IReadOnlyList<string>>(Workflow, input, context);
private async Task<IReadOnlyList<string>> Workflow(object input, IDurableContext ctx)
{
IBatchResult<string> result = await ctx.ParallelAsync(
new Func<IDurableContext, CancellationToken, Task<string>>[]
{
async (branch, ct) => await branch.StepAsync(
async (_, _) => "inventory ok", name: "check-inventory"),
async (branch, ct) => await branch.StepAsync(
async (_, _) => "payment ok", name: "check-payment"),
async (branch, ct) => await branch.StepAsync(
async (_, _) => "shipping ok", name: "check-shipping"),
},
name: "check-services");
return result.GetResults();
}
}
Method signature¶
context.parallel¶
// Named overload
parallel<TOutput>(
name: string | undefined,
branches: (ParallelFunc<TOutput> | NamedParallelBranch<TOutput>)[],
config?: ParallelConfig<TOutput>,
): DurablePromise<BatchResult<TOutput>>
// Unnamed overload
parallel<TOutput>(
branches: (ParallelFunc<TOutput> | NamedParallelBranch<TOutput>)[],
config?: ParallelConfig<TOutput>,
): DurablePromise<BatchResult<TOutput>>
Parameters:
name(optional) A name for the parallel operation. Passundefinedto omit.branchesAn array ofParallelFuncorNamedParallelBranchobjects.config(optional) AParallelConfig<TOutput>object.
Returns: DurablePromise<BatchResult<TOutput>>. Use await to get the result.
Throws: Branch exceptions are captured in the BatchResult. Call throwIfError()
to re-throw the first failure.
ParallelFunc / NamedParallelBranch
Each element in branches is either a plain function or a named branch object:
type ParallelFunc<TResult> = (context: DurableContext) => Promise<TResult>
interface NamedParallelBranch<TResult> {
name?: string;
func: ParallelFunc<TResult>;
}
name(optional) A name for this branch.funcAn async function receiving aDurableContextand returningPromise<TResult>.
Use NamedParallelBranch to give an inline lambda a name without defining a named
function.
def parallel(
self,
functions: Sequence[Callable[[DurableContext], T] | ParallelBranch[T]],
name: str | None = None,
config: ParallelConfig | None = None,
) -> BatchResult[T]: ...
Parameters:
functionsA sequence of branches. Each element is either a plain callable(ctx: DurableContext) -> Tor aParallelBranch[T]wrapper that pairs a callable with a name.name(optional) A name for the parallel operation.config(optional) AParallelConfigobject.
Returns: BatchResult[T].
Raises: Branch exceptions are captured in the BatchResult. Call throw_if_error()
to re-raise the first failure.
ParallelBranch
Wrap a callable in ParallelBranch to give a branch a custom name in execution
history without defining a named function. The durable_parallel_branch decorator
produces the same wrapper from a function.
ParallelDurableFuture parallel(String name)
ParallelDurableFuture parallel(String name, ParallelConfig config)
Parameters:
name(required) A name for the parallel operation.config(optional) AParallelConfigobject.
Returns: ParallelResult from get().
Throws: Branch exceptions are captured in ParallelResult. Inspect succeeded and
failed counts to detect failures.
ParallelDurableFuture
parallel() returns a ParallelDurableFuture. Call branch() to register and
immediately start each branch, then call get() to block until all complete.
interface ParallelDurableFuture extends AutoCloseable, DurableFuture<ParallelResult> {
<T> DurableFuture<T> branch(String name, Class<T> resultType,
Function<DurableContext, T> func);
<T> DurableFuture<T> branch(String name, TypeToken<T> resultType,
Function<DurableContext, T> func);
<T> DurableFuture<T> branch(String name, Class<T> resultType,
Function<DurableContext, T> func,
ParallelBranchConfig config);
ParallelResult get(); // blocks until all branches complete
void close(); // calls get() if not already called
}
Parameters for branch():
name(required) A name for this branch.resultTypeClass<T>orTypeToken<T>for deserialization.funcFunction<DurableContext, T>to execute in the branch's child context.config(optional)ParallelBranchConfigfor per-branch serialization.
Returns from branch(): DurableFuture<T>. DurableFuture<T> is the common return
type for all async Java SDK operations. Call .get() on it after parallel.get()
returns to retrieve that branch's individual result.
Tip
Use try-with-resources to guarantee get() is called even if you throw an exception
before reaching it explicitly.
ParallelBranchConfig
ParallelBranchConfig sets a custom SerDes for a single branch, overriding the
handler-level default set on DurableConfig.
// Branches of the same result type.
func Parallel[O any](ctx Context, name string, branches []Branch[O], opts ...BatchOption) (BatchResult[O], error)
type Branch[O any] struct {
Name string
Func func(Context) (O, error)
}
// Branches of different result types.
func ParallelMixed(ctx Context, name string, branches []AnyBranch, opts ...BatchOption) (BatchResult[json.RawMessage], error)
func NewTypedBranch[T any](name string, fn func(Context) (T, error), opts ...TypedBranchOption) *TypedBranch[T]
func (b *TypedBranch[T]) Result(res BatchResult[json.RawMessage]) (T, error)
Parameters:
ctxThe durable context.name(required) A name for the parallel operation. Pass""to omit it.branchesA[]Branch[O]. EachBranchhas aName(an empty name becomesparallel-branch-<index>) and aFuncthat receives the branch's owndurable.Context.opts(optional) Zero or moreBatchOptionvalues. See ParallelConfig.
Returns: (BatchResult[O], error). Branch failures are captured in the
BatchResult.
Errors: The same rules as Map. The batch fails as a unit when its
Reason is CompletionFailureToleranceExceeded or CompletionCustomFailed.
Parallel then returns the populated BatchResult together with a
*BatchError. It returns a *BatchCompletionError instead when a custom
decision failed the batch and no branch failed. A failure within the
configured tolerance returns a nil error. Any other error (an invalid
option, suspension, a checkpoint failure) comes with a zero BatchResult.
Return it unchanged. See Error handling.
For branches of different result types, use ParallelMixed with
NewTypedBranch. Each branch keeps its own result type, and
TypedBranch.Result decodes that branch's value from the returned
BatchResult[json.RawMessage]. For a failed branch it returns the branch's
error. For a branch that never started or was abandoned it returns a
*durable.BranchNotCompletedError.
pub fn parallel<Branches, O>(&self, branches: Branches) -> ParallelBuilder<O>
where
Branches: IntoIterator<Item = Branch<O>>,
O: Send + 'static,
...
impl<O: Send + 'static> Branch<O> {
pub fn new<F, Fut>(name: impl Into<String>, factory: F) -> Self
where
F: FnOnce(DurableContext) -> Fut + Send + 'static,
Fut: Future<Output = Result<O, BoxError>> + Send + 'static,
...
pub fn unnamed<F, Fut>(factory: F) -> Self
where
F: FnOnce(DurableContext) -> Fut + Send + 'static,
Fut: Future<Output = Result<O, BoxError>> + Send + 'static,
...
}
impl<O, IS, RS> IntoFuture for ParallelBuilder<O, IS, RS>
...
type Output = Result<Vec<O>, OperationError>;
...
pub async fn await_batch(self) -> Result<BatchResult<O>, OperationError>
...
pub fn spawn_batch(self) -> DurableFuture<BatchResult<O>>
...
pub fn future(self) -> DurableFuture<Vec<O>>
...
pub fn spawn(self) -> DurableFuture<Vec<O>>
...
// Branches of different result types.
pub fn parallel_mixed(&self, branches: crate::BranchSet) -> ParallelMixedBuilder
...
pub fn add<T, F, Fut>(&mut self, name: impl Into<String>, factory: F) -> BranchHandle<T>
where
T: serde::Serialize + serde::de::DeserializeOwned + Send + 'static,
F: FnOnce(DurableContext) -> Fut + Send + 'static,
Fut: Future<Output = Result<T, BoxError>> + Send + 'static,
...
pub fn summary(
mut self,
summary: impl Fn(&BatchResult<crate::future::BranchValue>) -> String + Send + Sync + 'static,
) -> Self
...
pub fn spawn(self) -> DurableFuture<CompletionReason>
...
impl<RS> IntoFuture for ParallelMixedBuilder<RS>
...
type Output = Result<CompletionReason, OperationError>;
...
pub fn key(&self) -> BranchKey<T>
...
pub fn into_result(self) -> Result<T, OperationError>
...
pub fn value<T: 'static>(&self, key: &crate::BranchKey<T>) -> Option<&T>
Parameters:
branchesAnyIntoIteratorofdurable::Branch<O>values. Build a branch withBranch::new(name, factory)orBranch::unnamed(factory). The factory receives the branch's ownDurableContext, and the SDK calls it when it starts the branch. A branch fromBranch::unnamed, or with an empty name, is namedparallel-branch-<index>.
parallel returns a ParallelBuilder<O>. Set the name and the options with its
methods, such as .name("check-services"), and then await it. Without
.name(...) the parallel operation is unnamed. See
ParallelConfig.
Returns: .await gives Result<Vec<O>, durable::OperationError>, the results of
the succeeded branches in input order. .await_batch().await gives the whole
BatchResult<O>. With the default durable::JsonSerdes, O must implement
serde::Serialize and serde::de::DeserializeOwned. See
Result types. .future() returns a lazy
durable::DurableFuture<Vec<O>> for ctx.join_all, ctx.try_join_all, ctx.race,
or ctx.select_ok. .spawn() and .spawn_batch() start the parallel operation at
once.
Errors: .await returns an error when the batch completes with
CompletionReason::FailureToleranceExceeded, which the default fail-fast
configuration gives at the first branch failure, or with
CompletionReason::CustomCompletionFailed. When a branch failed,
durable::OperationErrorKind::ChildContext contains a child error whose kind is
durable::ChildContextErrorKind::ChildFailed, and wire() holds the branch's
recorded failure. A custom failed outcome with no failed branch has child kind
BatchCompletionFailed and recorded type BatchCompletionError. Failure tolerance
exceeded with no failed branch has child kind Internal. .await_batch() returns
these branch and completion outcomes in the BatchResult instead. Both forms can
return an OperationError for a task ownership violation. A panic in a branch
propagates to the caller. See Error handling.
For branches of different result types, use parallel_mixed with a
durable::BranchSet. BranchSet::add adds a branch and returns a
durable::BranchHandle<T> for its result. BranchSet::add_with_serdes also sets
the serializer of that branch. .await on parallel_mixed returns the
CompletionReason, and returns an error in the same cases as parallel. .spawn()
starts it at once and returns a durable::DurableFuture<CompletionReason>.
.summary(...) sets a summary for a batch result too large to checkpoint. The
summary reads each branch's value with BatchResult::value and the key that
BranchHandle::key returns. See Checkpointing. After the
operation returns, BranchHandle::into_result gives the branch's value or its
error. For a branch that never started, or was still running when the batch
completed, it returns an error of kind
durable::ChildContextErrorKind::NotCompleted.
Task<IBatchResult<T>> ParallelAsync<T>(
IReadOnlyList<Func<IDurableContext, CancellationToken, Task<T>>> branches,
string? name = null,
ParallelConfig? config = null,
CancellationToken cancellationToken = default)
Task<IBatchResult<T>> ParallelAsync<T>(
IReadOnlyList<DurableBranch<T>> branches,
string? name = null,
ParallelConfig? config = null,
CancellationToken cancellationToken = default)
Parameters:
branchesThe branches to run concurrently, either as plainFunc<IDurableContext, CancellationToken, Task<T>>delegates or as namedDurableBranch<T>records.name(optional) A name for the parallel operation. Omit it to infer one from the call site.config(optional) AParallelConfigobject.cancellationToken(optional) A token linked with the SDK's workflow-shutdown signal, forwarded to each branch.
Returns: Task<IBatchResult<T>>. Use await to get the result.
Throws: Branch exceptions are captured in the IBatchResult. A completion-criteria
violation surfaces as ParallelException when awaited. Call ThrowIfError() to
re-throw the first branch failure explicitly.
DurableBranch<T>
Use the second overload to give each branch a name. DurableBranch<T> is a record
pairing a name with the branch function; the name surfaces on IBatchItem<T>.Name.
public sealed record DurableBranch<T>(
string Name,
Func<IDurableContext, CancellationToken, Task<T>> Func);
Name(required) A name for this branch.FuncAn async function receiving the branch'sIDurableContextand aCancellationToken, returningTask<T>.
ParallelConfig¶
interface ParallelConfig<TResult> {
maxConcurrency?: number;
completionConfig?: CompletionConfig;
serdes?: Serdes<BatchResult<TResult>>;
itemSerdes?: Serdes<TResult>;
summaryGenerator?: (result: BatchResult<TResult>) => string;
nesting?: NestingType;
}
Parameters:
maxConcurrency(optional) Maximum branches running at once. Default: unlimited.completionConfig(optional) When to stop. Default: wait for all branches.serdes(optional) CustomSerdesfor theBatchResult.itemSerdes(optional) CustomSerdesfor individual branch results.summaryGenerator(optional) A function invoked when the serializedBatchResultexceeds 256KB. See Checkpointing.nesting(optional)NestingType.NESTED(default) orNestingType.FLAT. See Nesting.
@dataclass(frozen=True)
class ParallelConfig:
max_concurrency: int | None = None
completion_config: CompletionConfig = CompletionConfig.all_successful()
serdes: SerDes | None = None
item_serdes: SerDes | None = None
summary_generator: SummaryGenerator | None = None
nesting_type: NestingType = NestingType.NESTED
Parameters:
max_concurrency(optional) Maximum branches running at once. Default: unlimited.completion_config(optional) When to stop. Default:CompletionConfig.all_successful().serdes(optional) CustomSerDesfor theBatchResult.item_serdes(optional) CustomSerDesfor individual branch results.summary_generator(optional) A callable invoked when the serializedBatchResultexceeds 256KB. See Checkpointing.nesting_type(optional)NestingType.NESTED(default) orNestingType.FLAT. See Nesting.
ParallelConfig.builder()
.maxConcurrency(Integer) // optional
.completionConfig(CompletionConfig) // optional
.nestingType(NestingType) // optional
.build()
Parameters:
maxConcurrency(optional) Maximum branches running at once. Default: unlimited.completionConfig(optional) When to stop. Default:CompletionConfig.allCompleted().nestingType(optional)NestingType.NESTED(default) orNestingType.FLAT. See Nesting.
Configure Parallel with the same BatchOption values as Map, passed as trailing
arguments. Name branches with Branch.Name.
func WithMaxConcurrency(n int) BatchOption
func WithCompletion(c CompletionConfig) BatchOption
func WithItemNamer(namer func(index int) string) BatchOption
func WithNesting(m NestingMode) BatchOption
func WithBatchSummary[O any](fn func(result BatchResult[O]) string) BatchOption
func WithBatchSerdes(s Serdes) BatchOption
func WithBatchResultSerdes(s Serdes) BatchOption
Parameters:
WithMaxConcurrencyMaximum branches running at once. Zero or negative is invalid. Default: unlimited.WithCompletionWhen to stop. Default: fail-fast. See CompletionConfig.WithItemNamerNames each branch from its zero-based index. It replaces everyBranch.Name. PreferBranch.Name.WithNestingNestingNormal(default) orNestingFlat. See Nesting.WithBatchSummaryA summary for an oversized result. See Checkpointing.WithBatchSerdesSerializer for each branch result.WithBatchResultSerdesSerializer for the wholeBatchResult.
ToleratedFailurePercentage is supported for parallel.
Configure parallel with methods on the ParallelBuilder it returns. Call them
before you await the builder. Name branches with Branch::new.
impl<O: Send + 'static, IS, RS> ParallelBuilder<O, IS, RS> {
pub fn name(mut self, name: impl Into<String>) -> Self
...
pub fn max_concurrency(mut self, max: usize) -> Self
...
pub fn completion(mut self, config: CompletionConfig) -> Self
...
pub fn serdes<IS2>(self, serdes: IS2) -> ParallelBuilder<O, IS2, RS>
where
IS2: Serdes<O>,
...
pub fn result_serdes<RS2>(self, serdes: RS2) -> ParallelBuilder<O, IS, RS2>
where
RS2: Serdes<String>,
...
pub fn nesting(mut self, mode: NestingMode) -> Self
...
pub fn summary(
mut self,
summary: impl Fn(&BatchResult<O>) -> String + Send + Sync + 'static,
) -> Self
...
}
NestingMode is non-exhaustive, so a match needs a _ arm.
Parameters:
nameA name for the parallel operation. Default: unnamed.max_concurrencyMaximum branches running at once. Default: unlimited.0fails the execution with anInvalid max_concurrency: 0error, which the handler cannot catch.completionWhen to stop. Default: fail-fast. See CompletionConfig.serdesA customdurable::Serdes<O>for individual branch results. Default:durable::JsonSerdes. See Serialization.result_serdesA customdurable::Serdes<String>for the whole batch record, which it receives as JSON text. Itsdeserializemust return the exact text thatserializereceived. Default:durable::PassthroughSerdes, which stores the text unchanged.nestingNestingMode::Normal(default) orNestingMode::Flat. See Nesting.summaryA function invoked when the serialized batch result exceeds 256KB. See Checkpointing.
The builder that parallel_mixed returns has name, max_concurrency,
completion, result_serdes, nesting, and summary. Set the serializer of each
of its branches with BranchSet::add_with_serdes. CompletionConfig,
NestingMode, and the result types are in the durable::builders::map_parallel
module.
tolerated_failure_percentage is supported for parallel.
public sealed class ParallelConfig
{
public int? MaxConcurrency { get; set; } // null = unlimited
public CompletionConfig CompletionConfig { get; set; } // default AllSuccessful()
public NestingType NestingType { get; set; } // default Nested
}
Parameters:
MaxConcurrency(optional) Maximum branches running at once.null(default) = unlimited. Must be at least 1 when set.CompletionConfig(optional) When to stop. Default:CompletionConfig.AllSuccessful().NestingType(optional)NestingType.Nested(default) orNestingType.Flat. See Nesting.
The SDK serializes results with the ILambdaSerializer registered on
ILambdaContext.Serializer; there is no per-operation serializer slot.
CompletionConfig¶
See Completion strategies for how CompletionConfig affects
execution and the completion status of the result.
@dataclass(frozen=True)
class CompletionConfig:
min_successful: int | None = None
tolerated_failure_count: int | None = None
tolerated_failure_percentage: int | float | None = None
should_complete: Callable[[CompletionStatus], CompletionDecision] | None = None
Use the threshold fields for count-based rules, or should_complete for a custom
predicate (see Completion strategies). should_complete
cannot be combined with the threshold fields.
Set the fields of a CompletionConfig and pass it with WithCompletion.
The threshold fields and ShouldComplete are mutually exclusive.
type CompletionConfig struct {
MinSuccessful int
ToleratedFailureCount *int
ToleratedFailurePercentage *int
ShouldComplete func(BatchProgress) CompletionDecision
}
type BatchProgress struct {
TotalCount int
CompletedCount int
SuccessCount int
FailureCount int
Items []BatchItemProgress
}
type BatchItemProgress struct {
Index int
Name string
Status BatchItemStatus
}
func ContinueBatch() CompletionDecision
func CompleteBatch(outcome CompletionOutcome) CompletionDecision
type CompletionOutcome int
const (
CompletionOutcomeSucceeded CompletionOutcome = 1
CompletionOutcomeFailed CompletionOutcome = 2
)
MinSuccessfulCompletes the batch once this many branches succeed. Zero leaves it unset.ToleratedFailureCountFails the batch once more than this many branches fail. Nil leaves it unset.aws.Int(0)fails on the first failure.ToleratedFailurePercentageFails the batch once the failure percentage, computed against the total branch count, is strictly greater than this value. Nil leaves it unset.aws.Int(0)fails on the first failure.ShouldCompleteA custom predicate. It cannot be combined with the threshold fields.
Set the pointer fields with any *int, for example aws.Int from
github.com/aws/aws-sdk-go-v2/aws. The default (no WithCompletion) is
fail-fast. To run every branch regardless of failures, set
ToleratedFailurePercentage: aws.Int(100), which is never exceeded. For
first-successful, set MinSuccessful: 1.
Build a CompletionConfig with one of its constructors, or with
CompletionConfig::builder() to set several thresholds. Pass it with
.completion(...).
impl CompletionConfig {
pub fn builder() -> CompletionConfigBuilder
...
pub fn with_min_successful(min: usize) -> Self
...
pub fn with_tolerated_failure_count(count: usize) -> Self
...
pub fn with_tolerated_failure_percentage(
pct: f64,
) -> Result<Self, CompletionConfigValidationError>
...
pub fn with_completion_predicate<F>(predicate: F) -> Self
where
F: Fn(&BatchStats<'_>) -> CompletionDecision + Send + Sync + 'static,
...
}
impl CompletionConfigBuilder {
...
pub fn min_successful(mut self, min: usize) -> Self
...
pub fn tolerated_failure_count(mut self, count: usize) -> Self
...
pub fn tolerated_failure_percentage(mut self, pct: f64) -> Self
...
pub fn completion_predicate<F>(mut self, predicate: F) -> Self
where
F: Fn(&BatchStats<'_>) -> CompletionDecision + Send + Sync + 'static,
...
pub fn build(self) -> Result<CompletionConfig, CompletionConfigValidationError>
...
}
pub enum CompletionDecision {
Continue,
Complete(CompletionOutcome),
}
impl CompletionDecision {
pub fn complete(outcome: CompletionOutcome) -> Self
...
}
pub enum CompletionOutcome {
Succeeded,
Failed,
}
CompletionDecision and CompletionOutcome are non-exhaustive, so a match needs
a _ arm.
min_successfulCompletes the batch once this many branches succeed. On its own it tolerates every failure.tolerated_failure_countFails the batch once more than this many branches fail.0fails on the first failure.tolerated_failure_percentageFails the batch once the failure percentage, computed against the total branch count, is strictly greater than this value. The value must be finite and from 0.0 to 100.0. For any other value,with_tolerated_failure_percentage(...)andbuild()return aCompletionConfigValidationError, so an invalid value never reaches the parallel operation.completion_predicateA custom predicate.build()returns an error when it is combined with a threshold. See Completion strategies.
When several thresholds are set, the first one reached ends the batch. A concurrent
batch that resumes with recorded branch outcomes applies all of them, then checks
the thresholds once, in the order failure tolerance, every branch finished, and
min_successful. The default
(no .completion(...)) is fail-fast. To run every branch regardless of failures,
use CompletionConfig::with_tolerated_failure_percentage(100.0)?, which is never
exceeded. For first-successful, use CompletionConfig::with_min_successful(1).
CompletionConfig.AllSuccessful() // tolerate zero failures (the default)
CompletionConfig.AllCompleted() // run every branch; never auto-throws
CompletionConfig.FirstSuccessful() // resolve once one branch succeeds
// Or set the individual properties directly:
new CompletionConfig { MinSuccessful = 2 }
new CompletionConfig { ToleratedFailureCount = 1 }
new CompletionConfig { ToleratedFailurePercentage = 0.25 } // ratio in [0.0, 1.0]
AllSuccessful() is equivalent to ToleratedFailureCount = 0, and FirstSuccessful()
is equivalent to MinSuccessful = 1. Multiple criteria combine: the operation resolves
as soon as any criterion is met or violated.
Result types¶
interface BatchResult<TResult> {
all: BatchItem<TResult>[];
status: BatchItemStatus.SUCCEEDED | BatchItemStatus.FAILED;
completionReason: "ALL_COMPLETED" | "MIN_SUCCESSFUL_REACHED" | "FAILURE_TOLERANCE_EXCEEDED";
hasFailure: boolean;
successCount: number;
failureCount: number;
startedCount: number;
totalCount: number;
getResults(): TResult[];
getErrors(): ChildContextError[];
succeeded(): BatchItem<TResult>[];
failed(): BatchItem<TResult>[];
started(): BatchItem<TResult>[];
throwIfError(): void;
}
allallBatchItementries, one per branch, in input order. Iterate withitem.indexfor branch-indexed access when some branches fail.getResults()results of succeeded branches, preserving input ordergetErrors()ChildContextError[]for failed branchessucceeded()/failed()/started()BatchItem[]filtered by statussuccessCount/failureCount/startedCount/totalCountbranch countsstatusSUCCEEDEDif no failures,FAILEDotherwisecompletionReasonwhy the operation completed. See Completion strategies.hasFailuretrueif any branch failedthrowIfError()throws the first branch error, if any
interface BatchItem<TResult> {
index: number;
status: BatchItemStatus;
result?: TResult;
error?: ChildContextError;
}
enum BatchItemStatus {
SUCCEEDED = "SUCCEEDED",
FAILED = "FAILED",
STARTED = "STARTED",
}
indexposition of this branch in the input arraystatusSUCCEEDED,FAILED, orSTARTED(not yet complete)resultthe branch return value, present whenstatusisSUCCEEDEDerrorthe captured error, present whenstatusisFAILED
@dataclass(frozen=True)
class BatchResult(Generic[R]):
all: list[BatchItem[R]]
completion_reason: CompletionReason
def get_results(self) -> list[R]: ...
def get_errors(self) -> list[ErrorObject]: ...
def succeeded(self) -> list[BatchItem[R]]: ...
def failed(self) -> list[BatchItem[R]]: ...
def started(self) -> list[BatchItem[R]]: ...
def throw_if_error(self) -> None: ...
def to_dict(self) -> dict: ...
@property
def status(self) -> BatchItemStatus: ...
@property
def has_failure(self) -> bool: ...
@property
def success_count(self) -> int: ...
@property
def failure_count(self) -> int: ...
@property
def started_count(self) -> int: ...
@property
def total_count(self) -> int: ...
class CompletionReason(Enum):
ALL_COMPLETED = "ALL_COMPLETED"
MIN_SUCCESSFUL_REACHED = "MIN_SUCCESSFUL_REACHED"
FAILURE_TOLERANCE_EXCEEDED = "FAILURE_TOLERANCE_EXCEEDED"
allallBatchItementries, one per branch, in input order. Iterate withitem.indexfor branch-indexed access when some branches fail.get_results()results of succeeded branches, preserving input orderget_errors()list[ErrorObject]for failed branchessucceeded()/failed()/started()BatchItemlists filtered by statussuccess_count/failure_count/started_count/total_countbranch countsstatusBatchItemStatus.SUCCEEDEDif no failures,FAILEDotherwisecompletion_reasonwhy the operation completed. See Completion strategies.has_failureTrueif any branch failedthrow_if_error()raises the first failure:ChildContextErrorfor a failed branch,SerDesErrorif a branch result failed to serialize, orBatchCompletionErrorif a custom predicate failed the batchto_dict()serializes to a plain dict. Serializability depends onR.
@dataclass(frozen=True)
class BatchItem(Generic[R]):
index: int
status: BatchItemStatus
result: R | None = None
error: ErrorObject | None = None
def to_dict(self) -> dict: ...
class BatchItemStatus(Enum):
SUCCEEDED = "SUCCEEDED"
FAILED = "FAILED"
STARTED = "STARTED"
indexposition of this branch in the input sequencestatusSUCCEEDED,FAILED, orSTARTED(not yet complete)resultthe branch return value, present whenstatusisSUCCEEDEDerrorErrorObjectwith the captured error, present whenstatusisFAILEDto_dict()serializes to a plain dict. Serializability ofresultdepends onR.
record ParallelResult(
int size,
int succeeded,
int failed,
ConcurrencyCompletionStatus completionStatus
) {}
enum ConcurrencyCompletionStatus {
ALL_COMPLETED,
MIN_SUCCESSFUL_REACHED,
FAILURE_TOLERANCE_EXCEEDED,
CUSTOM_COMPLETION_SUCCEEDED,
CUSTOM_COMPLETION_FAILED
}
sizetotal number of registered branchessucceedednumber of branches that succeededfailednumber of branches that failedcompletionStatuswhy the operation completed. See Completion strategies.
ConcurrencyCompletionStatus.isSucceeded() returns true for ALL_COMPLETED,
MIN_SUCCESSFUL_REACHED, and CUSTOM_COMPLETION_SUCCEEDED. To check if any branch
failed, use result.failed() > 0 (where result is a ParallelResult).
ParallelResult contains only aggregate counts. To get individual branch results, hold
the DurableFuture<T> returned by each branch() call and call .get() on it after
parallel.get() returns. Results are available in the order branches were registered.
Parallel and Map return the same BatchResult[O]. It carries each
branch's result and error.
type BatchResult[O any] struct {
Items []BatchItem[O]
Reason CompletionReason
}
func (r BatchResult[O]) Results() []O
func (r BatchResult[O]) Succeeded() []BatchItem[O]
func (r BatchResult[O]) Failed() []BatchItem[O]
func (r BatchResult[O]) Started() []BatchItem[O]
func (r BatchResult[O]) Errors() []error
func (r BatchResult[O]) HasFailure() bool
func (r BatchResult[O]) SuccessCount() int
func (r BatchResult[O]) FailureCount() int
func (r BatchResult[O]) StartedCount() int
func (r BatchResult[O]) TotalCount() int
func (r BatchResult[O]) Status() BatchItemStatus
func (r BatchResult[O]) Item(name string) *BatchItem[O]
func (r BatchResult[O]) Result(name string) (value O, ok bool)
type BatchItem[O any] struct {
Index int
Name string
Status BatchItemStatus
Result O
Err error
}
type BatchItemStatus int
const (
BatchItemNotStarted BatchItemStatus = 0
BatchItemSucceeded BatchItemStatus = 1
BatchItemFailed BatchItemStatus = 2
BatchItemStarted BatchItemStatus = 4
)
type CompletionReason int
const (
CompletionAllCompleted CompletionReason = 1
CompletionMinSuccessfulReached CompletionReason = 2
CompletionFailureToleranceExceeded CompletionReason = 3
CompletionCustomSucceeded CompletionReason = 4
CompletionCustomFailed CompletionReason = 5
)
Itemsper-branch outcomes in input order. A branch started and then abandoned on early completion is included withBatchItemStarted. Branches that never started are omitted.Results()successful results in input order.Errors()errors of failed branches, in input order. Each is rebuilt from its checkpoint record. InNestingNormaleach is a*durable.ChildContextErrornamed after the branch. InNestingFlateach is the rebuilt error the branch function returned.errors.Asmatches an SDK error inside, such as*durable.StepError, but not your own error types. InNestingNormal, match your own types onChildContextError.ErrorType.Succeeded()/Failed()/Started()branches filtered by status.SuccessCount()/FailureCount()/StartedCount()/TotalCount()branch counts.TotalCount()excludes branches that never started.Status()BatchItemFailedif any branch failed or the batch failed as a unit, elseBatchItemSucceeded. A custom decision sets it directly. A failure within tolerance still givesBatchItemFailedwith a nil error.Item(name)/Result(name)look up one branch by its name.Reasonwhy the batch completed.
BatchItemStatus.String() and CompletionReason.String() return the wire
forms, such as SUCCEEDED and ALL_COMPLETED.
Inspect the returned error and the result.
.await_batch() returns a BatchResult<O>, the same type that map returns. It
carries each branch's result and error.
pub struct BatchResult<O> {
pub items: Vec<BatchItem<O>>,
pub reason: CompletionReason,
}
impl<O> BatchResult<O> {
...
pub fn results(&self) -> impl Iterator<Item = &O> + '_
...
pub fn success_count(&self) -> usize
...
pub fn failure_count(&self) -> usize
...
pub fn has_failure(&self) -> bool
...
pub fn status(&self) -> BatchStatus
...
pub fn total_count(&self) -> usize
...
pub fn errors(&self) -> impl Iterator<Item = BatchError<'_>> + '_
...
pub fn succeeded(&self) -> impl Iterator<Item = &BatchItem<O>> + '_
...
pub fn failed(&self) -> impl Iterator<Item = &BatchItem<O>> + '_
...
pub fn started(&self) -> impl Iterator<Item = &BatchItem<O>> + '_
...
pub fn started_count(&self) -> usize
...
pub fn into_result(self) -> Result<Self, OperationError>
...
}
...
pub enum BatchItemStatus {
Succeeded,
Failed,
Started,
}
pub struct BatchItem<O> {
pub index: usize,
pub name: String,
pub status: BatchItemStatus,
pub result: Option<O>,
pub error_message: Option<String>,
pub error_type: Option<String>,
pub error_data: Option<String>,
pub stack_trace: Vec<String>,
}
...
pub enum BatchStatus {
Succeeded,
Failed,
}
...
pub struct BatchError<'a> {
pub index: usize,
pub name: &'a str,
pub message: &'a str,
pub error_type: Option<&'a str>,
}
pub enum CompletionReason {
AllCompleted,
MinSuccessfulReached,
FailureToleranceExceeded,
CustomCompletionSucceeded,
CustomCompletionFailed,
}
The structs and enums in this block are non-exhaustive. Enum matches need a _ arm,
and struct patterns need ...
itemsoneBatchItemper started branch, in input order. Branches that never started are omitted.reasonwhy the operation completed. See Completion strategies.results()an iterator over references to the results of succeeded branches, in input ordererrors()an iterator with aBatchErrorfor each failed branch, with its index, name, message, and error typesucceeded()/failed()/started()iterators over the branches with that statussuccess_count()/failure_count()/started_count()/total_count()branch counts.total_count()excludes branches that never started.status()the outcome of a custom predicate when one completed the batch. OtherwiseBatchStatus::Failedif any branch failed, also within the failure tolerance, andBatchStatus::Succeededif none failed.has_failure()trueif any branch failedinto_result()returns the first failed branch'sChildFailederror, if any. When no branch failed and the status isFailed, it returns aBatchCompletionFailederror. Otherwise it returns theBatchResult. See Errors.
A BatchItem holds result when its status is BatchItemStatus::Succeeded, and
the recorded failure (error_message, error_type, error_data, stack_trace)
when it is BatchItemStatus::Failed. name is the name from Branch::new, or
parallel-branch-<index>. BatchItemStatus::Started marks a branch that was
running when the batch completed. CompletionReason::as_str() and
BatchStatus::as_str() return the wire forms, such as ALL_COMPLETED and
SUCCEEDED.
parallel_mixed returns the CompletionReason. Read each branch's outcome from its
BranchHandle.
public interface IBatchResult<T> : IBatchResult
{
IReadOnlyList<IBatchItem<T>> All { get; }
IReadOnlyList<IBatchItem<T>> Succeeded { get; }
IReadOnlyList<IBatchItem<T>> Failed { get; }
IReadOnlyList<IBatchItem<T>> Started { get; }
IReadOnlyList<T> GetResults();
IReadOnlyList<DurableExecutionException> GetErrors();
void ThrowIfError();
}
public interface IBatchResult
{
CompletionReason CompletionReason { get; }
bool HasFailure { get; }
int SuccessCount { get; }
int FailureCount { get; }
int StartedCount { get; }
int TotalCount { get; }
}
AllallIBatchItementries, one per branch, in original index order. Iterate withitem.Indexfor branch-indexed access when some branches fail.Succeeded/Failed/StartedIBatchItemlists filtered by status, in original index orderGetResults()results of succeeded branches, preserving input order. Skips failed and started items, so it never throws on partial-failure batchesGetErrors()DurableExecutionExceptionlist for failed branchesSuccessCount/FailureCount/StartedCount/TotalCountbranch countsHasFailuretrueif any branch failedCompletionReasonwhy the operation completed. See Completion strategies.ThrowIfError()throws the first failed branch'sError, if any
public interface IBatchItem<T>
{
int Index { get; }
string? Name { get; }
BatchItemStatus Status { get; }
T? Result { get; } // set when Status is Succeeded
DurableExecutionException? Error { get; } // set when Status is Failed
}
public enum BatchItemStatus
{
Succeeded,
Failed,
Started
}
public enum CompletionReason
{
AllCompleted,
MinSuccessfulReached,
FailureToleranceExceeded
}
Indexzero-based position of this branch in the input listNamethe branch name (fromDurableBranch<T>.Name), if anyStatusSucceeded,Failed, orStarted(not dispatched before the operation resolved)Resultthe branch return value, present whenStatusisSucceededErrorthe captured error, present whenStatusisFailed
Branch functions¶
Each branch receives a DurableContext and can use any durable operation such as steps,
waits, child contexts, or nested parallel operations. Branches run in
child contexts, so they do not share state with each other or with
the parent context.
A branch is a ParallelFunc (plain async function) or a NamedParallelBranch (object
with name and func). Use NamedParallelBranch to give an inline lambda a name
without defining a named function.
import {
BatchResult,
DurableContext,
withDurableExecution,
} from "@aws/durable-execution-sdk-js";
// Plain function branch
async function taskA(ctx: DurableContext): Promise<string> {
return ctx.step("run-a", async () => "a done");
}
export const handler = withDurableExecution(
async (event: any, context: DurableContext): Promise<string[]> => {
const result: BatchResult<string> = await context.parallel("process", [
// ParallelFunc: plain async function
taskA,
// NamedParallelBranch: object with name and func
{ name: "task-b", func: async (ctx) => ctx.step("run-b", async () => "b done") },
]);
return result.getResults();
},
);
A branch is a synchronous callable that receives a DurableContext and returns T,
or a ParallelBranch[T] wrapping such a callable with a name. Wrap a branch in
ParallelBranch to name it in execution history without defining a named function.
from aws_durable_execution_sdk_python import (
BatchResult,
DurableContext,
ParallelBranch,
durable_execution,
)
def task_a(ctx: DurableContext) -> str:
return ctx.step(lambda _: "a done", name="run-a")
def task_b(ctx: DurableContext) -> str:
return ctx.step(lambda _: "b done", name="run-b")
@durable_execution
def handler(event: dict, context: DurableContext) -> list[str]:
result: BatchResult[str] = context.parallel(
[
# A plain callable runs as an unnamed branch
task_a,
# Wrap a callable in ParallelBranch to give the branch a name
ParallelBranch(func=task_b, name="task-b"),
],
name="process",
)
return result.get_results()
Each branch is registered via ParallelDurableFuture.branch(). The branch function is a
synchronous Function<DurableContext, T>.
import software.amazon.lambda.durable.DurableContext;
import software.amazon.lambda.durable.DurableHandler;
import software.amazon.lambda.durable.model.ParallelResult;
public class NamedBranches extends DurableHandler<Void, ParallelResult> {
@Override
public ParallelResult handleRequest(Void input, DurableContext context) {
try (var parallel = context.parallel("process")) {
parallel.branch("task-a", String.class,
ctx -> ctx.step("run-a", String.class, s -> "a done"));
parallel.branch("task-b", String.class,
ctx -> ctx.step("run-b", String.class, s -> "b done"));
return parallel.get();
}
}
}
A branch is a Branch[O] with a Name and a Func. Set Name to name the
branch. An empty Name is named parallel-branch-<index>. The Func
receives the branch's own durable.Context.
// Package main names parallel branches. A branch with an empty Name is named
// "parallel-branch-<index>".
package main
import "github.com/aws/aws-durable-execution-sdk-go/durable"
func taskA(ctx durable.Context) (string, error) {
return durable.Step(ctx, "run-a", func(durable.StepContext) (string, error) {
return "a done", nil
})
}
func handler(ctx durable.Context, _ any) ([]string, error) {
result, err := durable.Parallel(ctx, "process", []durable.Branch[string]{
{Func: taskA},
{Name: "task-b", Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "run-b", func(durable.StepContext) (string, error) {
return "b done", nil
})
}},
})
if err != nil {
return nil, err
}
return result.Results(), nil
}
func main() { durable.Start(handler) }
A branch is a durable::Branch<O>, built from a function or closure that receives
the branch's DurableContext and returns a future of
Result<O, durable::BoxError>. Branch::new(name, ...) names the branch.
Branch::unnamed(...) records it as parallel-branch-<index>. Pass an async fn
directly, as task_a is passed here.
use aws_durable_execution_sdk as durable;
async fn task_a(ctx: durable::DurableContext) -> Result<String, durable::BoxError> {
Ok(ctx
.step(|_| async { Ok("a done".to_owned()) })
.name("run-a")
.await?)
}
async fn handler(
_event: serde_json::Value,
ctx: durable::DurableContext,
) -> Result<Vec<String>, durable::BoxError> {
let results = ctx
.parallel([
durable::Branch::unnamed(task_a),
durable::Branch::new("task-b", |ctx| async move {
Ok(ctx
.step(|_| async { Ok("b done".to_owned()) })
.name("run-b")
.await?)
}),
])
.name("process")
.await?;
Ok(results)
}
#[tokio::main]
async fn main() -> Result<(), lambda_runtime::Error> {
durable::init_default_subscriber()?;
durable::run(handler).await
}
A branch is a plain Func<IDurableContext, CancellationToken, Task<T>>, or a
DurableBranch<T> record to give it a name. Use the named overload to surface a name
on IBatchItem<T>.Name without defining a named method.
using Amazon.Lambda.Core;
using Amazon.Lambda.DurableExecution;
public class NamedBranchesExample
{
public Task<DurableExecutionInvocationOutput> Handler(
DurableExecutionInvocationInput input, ILambdaContext context)
=> DurableFunction.WrapAsync<object, IReadOnlyList<string>>(Workflow, input, context);
private async Task<IReadOnlyList<string>> Workflow(object input, IDurableContext ctx)
{
// Each DurableBranch carries a name surfaced on IBatchItem.Name.
IBatchResult<string> result = await ctx.ParallelAsync(
new[]
{
new DurableBranch<string>("task-a", async (branch, ct) =>
await branch.StepAsync(async (_, _) => "a done", name: "run-a")),
new DurableBranch<string>("task-b", async (branch, ct) =>
await branch.StepAsync(async (_, _) => "b done", name: "run-b")),
},
name: "process");
return result.GetResults();
}
}
Pass arguments to branches¶
Capture arguments in a closure:
import {
BatchResult,
DurableContext,
withDurableExecution,
} from "@aws/durable-execution-sdk-js";
export const handler = withDurableExecution(
async (event: any, context: DurableContext): Promise<string[]> => {
const items = ["a", "b", "c"];
const result: BatchResult<string> = await context.parallel(
"process-items",
items.map((item) => async (ctx: DurableContext) =>
ctx.step(`process-${item}`, async () => `processed ${item}`),
),
);
return result.getResults();
},
);
Use a factory function to bind arguments. Avoid using loop variables directly in lambdas, as Python closures capture by reference.
from aws_durable_execution_sdk_python import (
BatchResult,
DurableContext,
durable_execution,
)
def make_branch(item: str):
def branch(ctx: DurableContext) -> str:
return ctx.step(lambda _: f"processed {item}", name=f"process-{item}")
return branch
@durable_execution
def handler(event: dict, context: DurableContext) -> list[str]:
items = ["a", "b", "c"]
result: BatchResult[str] = context.parallel(
[make_branch(item) for item in items],
name="process-items",
)
return result.get_results()
Capture arguments in a lambda. Java lambdas require effectively final variables.
import java.util.List;
import software.amazon.lambda.durable.DurableContext;
import software.amazon.lambda.durable.DurableHandler;
import software.amazon.lambda.durable.model.ParallelResult;
public class PassArguments extends DurableHandler<Void, ParallelResult> {
@Override
public ParallelResult handleRequest(Void input, DurableContext context) {
var items = List.of("a", "b", "c");
try (var parallel = context.parallel("process-items")) {
for (var item : items) {
parallel.branch("process-" + item, String.class,
ctx -> ctx.step("run-" + item, String.class, s -> "processed " + item));
}
return parallel.get();
}
}
}
Capture arguments in the branch closure. In a module that declares Go 1.22 or later, each loop iteration has its own variable. So a branch built in a loop captures its own value.
// Package main builds parallel branches in a loop, capturing a per-branch
// argument in the branch closure. In a module that declares Go 1.22 or later,
// each iteration has its own loop variable, so the closure captures the value
// for its branch.
package main
import (
"fmt"
"github.com/aws/aws-durable-execution-sdk-go/durable"
)
func handler(ctx durable.Context, _ any) ([]string, error) {
items := []string{"a", "b", "c"}
branches := make([]durable.Branch[string], 0, len(items))
for _, item := range items {
branches = append(branches, durable.Branch[string]{
Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, fmt.Sprintf("process-%s", item),
func(durable.StepContext) (string, error) {
return "processed " + item, nil
})
},
})
}
result, err := durable.Parallel(ctx, "process-items", branches)
if err != nil {
return nil, err
}
return result.Results(), nil
}
func main() { durable.Start(handler) }
Capture arguments in a move closure. Each closure owns the values it captures, so
a branch built in a loop or by map gets its own value. The branch factory must be
'static, so capture owned values or &'static str values.
use aws_durable_execution_sdk as durable;
async fn handler(
_event: serde_json::Value,
ctx: durable::DurableContext,
) -> Result<Vec<String>, durable::BoxError> {
let items = ["a", "b", "c"];
let results = ctx
.parallel(items.map(|item| {
durable::Branch::unnamed(move |ctx| async move {
Ok(ctx
.step(move |_| async move { Ok(format!("processed {item}")) })
.name(format!("process-{item}"))
.await?)
})
}))
.name("process-items")
.await?;
Ok(results)
}
#[tokio::main]
async fn main() -> Result<(), lambda_runtime::Error> {
durable::init_default_subscriber()?;
durable::run(handler).await
}
Capture arguments in the closure. Copy the loop variable to a local so each branch captures its own value.
using Amazon.Lambda.Core;
using Amazon.Lambda.DurableExecution;
public class PassArgumentsExample
{
public Task<DurableExecutionInvocationOutput> Handler(
DurableExecutionInvocationInput input, ILambdaContext context)
=> DurableFunction.WrapAsync<object, IReadOnlyList<string>>(Workflow, input, context);
private async Task<IReadOnlyList<string>> Workflow(object input, IDurableContext ctx)
{
var items = new[] { "a", "b", "c" };
// Capture each item in the closure. Copy the loop variable to a local
// so every branch captures its own value.
var branches = new List<DurableBranch<string>>();
foreach (var item in items)
{
var captured = item;
branches.Add(new DurableBranch<string>($"process-{captured}",
async (branch, ct) => await branch.StepAsync(
async (_, _) => $"processed {captured}", name: $"run-{captured}")));
}
IBatchResult<string> result = await ctx.ParallelAsync(branches, name: "process-items");
return result.GetResults();
}
}
Naming parallel operations¶
Name your parallel operations to make them easier to identify in logs and tests.
The name is the first argument. Pass undefined to omit it.
Pass name as a keyword argument. Omit it or pass None to leave it unnamed.
The name is always required. Each branch() call also requires a name. Pass null to
omit it.
The name is the required second argument. Pass "" to leave it unnamed. Name
each branch with Branch.Name. An empty name becomes
parallel-branch-<index>.
Set the name with .name(...). Omit the call to leave the operation unnamed. Name
each branch with Branch::new(name, ...). A branch from Branch::unnamed(...), or
with an empty name, is named parallel-branch-<index>.
The name is the optional name argument. Omit it to infer one from the call site. Use
the DurableBranch<T> overload to name each branch.
Configuration¶
Configure parallel behavior using ParallelConfig:
import {
BatchResult,
DurableContext,
NestingType,
withDurableExecution,
} from "@aws/durable-execution-sdk-js";
export const handler = withDurableExecution(
async (event: any, context: DurableContext): Promise<string | undefined> => {
const result: BatchResult<string> = await context.parallel(
"fetch-data",
[
async (ctx) => ctx.step("primary", async () => "primary result"),
async (ctx) => ctx.step("secondary", async () => "secondary result"),
async (ctx) => ctx.step("cache", async () => "cache result"),
],
{
maxConcurrency: 2,
completionConfig: { minSuccessful: 1 },
nesting: NestingType.FLAT,
},
);
return result.getResults()[0];
},
);
from aws_durable_execution_sdk_python import (
BatchResult,
DurableContext,
durable_execution,
)
from aws_durable_execution_sdk_python.config import (
CompletionConfig,
NestingType,
ParallelConfig,
)
def try_primary(ctx: DurableContext) -> str:
return ctx.step(lambda _: "primary result", name="primary")
def try_secondary(ctx: DurableContext) -> str:
return ctx.step(lambda _: "secondary result", name="secondary")
def try_cache(ctx: DurableContext) -> str:
return ctx.step(lambda _: "cache result", name="cache")
@durable_execution
def handler(event: dict, context: DurableContext) -> str | None:
config = ParallelConfig(
max_concurrency=2,
completion_config=CompletionConfig.first_successful(),
nesting_type=NestingType.FLAT,
)
result: BatchResult[str] = context.parallel(
[try_primary, try_secondary, try_cache],
name="fetch-data",
config=config,
)
results = result.get_results()
return results[0] if results else None
import software.amazon.lambda.durable.DurableContext;
import software.amazon.lambda.durable.DurableHandler;
import software.amazon.lambda.durable.config.CompletionConfig;
import software.amazon.lambda.durable.config.NestingType;
import software.amazon.lambda.durable.config.ParallelConfig;
import software.amazon.lambda.durable.model.ParallelResult;
public class ParallelConfigExample extends DurableHandler<Void, ParallelResult> {
@Override
public ParallelResult handleRequest(Void input, DurableContext context) {
var config = ParallelConfig.builder()
.maxConcurrency(2)
.completionConfig(CompletionConfig.firstSuccessful())
.nestingType(NestingType.FLAT)
.build();
try (var parallel = context.parallel("fetch-data", config)) {
parallel.branch("primary", String.class,
ctx -> ctx.step("primary", String.class, s -> "primary result"));
parallel.branch("secondary", String.class,
ctx -> ctx.step("secondary", String.class, s -> "secondary result"));
parallel.branch("cache", String.class,
ctx -> ctx.step("cache", String.class, s -> "cache result"));
return parallel.get();
}
}
}
// Package main configures a Parallel with bounded concurrency, a
// first-successful completion policy, and flat nesting.
package main
import "github.com/aws/aws-durable-execution-sdk-go/durable"
func handler(ctx durable.Context, _ any) (*string, error) {
result, err := durable.Parallel(ctx, "fetch-data", []durable.Branch[string]{
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "primary", func(durable.StepContext) (string, error) {
return "primary result", nil
})
}},
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "secondary", func(durable.StepContext) (string, error) {
return "secondary result", nil
})
}},
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "cache", func(durable.StepContext) (string, error) {
return "cache result", nil
})
}},
},
durable.WithMaxConcurrency(2),
durable.WithCompletion(durable.CompletionConfig{MinSuccessful: 1}),
durable.WithNesting(durable.NestingFlat),
)
if err != nil {
return nil, err
}
results := result.Results()
if len(results) == 0 {
return nil, nil
}
return &results[0], nil
}
func main() { durable.Start(handler) }
Set the options with methods on the builder that ctx.parallel returns. See
ParallelConfig.
use aws_durable_execution_sdk as durable;
use durable::builders::map_parallel::{CompletionConfig, NestingMode};
async fn handler(
_event: serde_json::Value,
ctx: durable::DurableContext,
) -> Result<Option<String>, durable::BoxError> {
let results = ctx
.parallel([
durable::Branch::unnamed(|ctx| async move {
Ok(ctx
.step(|_| async { Ok("primary result".to_owned()) })
.name("primary")
.await?)
}),
durable::Branch::unnamed(|ctx| async move {
Ok(ctx
.step(|_| async { Ok("secondary result".to_owned()) })
.name("secondary")
.await?)
}),
durable::Branch::unnamed(|ctx| async move {
Ok(ctx
.step(|_| async { Ok("cache result".to_owned()) })
.name("cache")
.await?)
}),
])
.name("fetch-data")
.max_concurrency(2)
.completion(CompletionConfig::with_min_successful(1))
.nesting(NestingMode::Flat)
.await?;
Ok(results.into_iter().next())
}
#[tokio::main]
async fn main() -> Result<(), lambda_runtime::Error> {
durable::init_default_subscriber()?;
durable::run(handler).await
}
using Amazon.Lambda.Core;
using Amazon.Lambda.DurableExecution;
public class ParallelConfigExample
{
public Task<DurableExecutionInvocationOutput> Handler(
DurableExecutionInvocationInput input, ILambdaContext context)
=> DurableFunction.WrapAsync<object, string?>(Workflow, input, context);
private async Task<string?> Workflow(object input, IDurableContext ctx)
{
var config = new ParallelConfig
{
MaxConcurrency = 2,
CompletionConfig = CompletionConfig.FirstSuccessful(),
NestingType = NestingType.Flat,
};
IBatchResult<string> result = await ctx.ParallelAsync(
new Func<IDurableContext, CancellationToken, Task<string>>[]
{
async (branch, ct) => await branch.StepAsync(
async (_, _) => "primary result", name: "primary"),
async (branch, ct) => await branch.StepAsync(
async (_, _) => "secondary result", name: "secondary"),
async (branch, ct) => await branch.StepAsync(
async (_, _) => "cache result", name: "cache"),
},
name: "fetch-data",
config: config);
return result.GetResults().FirstOrDefault();
}
}
Nesting¶
Nested mode is the default. The SDK records each branch context as a separate CONTEXT
operation and checkpoints the branch result there. Each branch appears separately in the
execution history.
In flat mode, the SDK uses a virtual context for each branch and omits the per-branch
CONTEXT operation. Durable operations inside the branch still checkpoint and appear as
children of the parallel operation. The SDK records the branch outcome with the parent
parallel operation.
Use flat mode for parallel operations with many branches when each branch performs few durable operations and you do not need each branch represented separately in the execution history. Flat mode removes one checkpointed operation per branch while preserving checkpoints for durable operations inside each branch.
Completion strategies¶
CompletionConfig controls when the parallel operation completes. When the operation
reaches the completion criteria, it will abandon branches that have not completed yet.
The abandoned branches will keep running in the background but cannot checkpoint their
results after the parent completes. The SDK makes a best-effort attempt to cancel
ongoing work in abandoned branches, but cancellation is not guaranteed.
The BatchResult's completionReason indicates the stop condition with which the
parallel operation completed. Branches that had not started yet do not appear in
result.all at all. Branches that had started but not completed yet appear with status
STARTED.
completionConfig |
Early exit completionReason |
Full completion completionReason |
|---|---|---|
{} or omitted |
FAILURE_TOLERANCE_EXCEEDED |
ALL_COMPLETED |
toleratedFailureCount=N |
FAILURE_TOLERANCE_EXCEEDED |
ALL_COMPLETED |
toleratedFailurePercentage=N |
FAILURE_TOLERANCE_EXCEEDED |
ALL_COMPLETED |
minSuccessful=N |
MIN_SUCCESSFUL_REACHED |
ALL_COMPLETED |
The BatchResult's completion_reason indicates the stop condition with which the
parallel operation completed. Branches that started but did not complete appear in
result.all with status STARTED. Branches that never started are omitted from
result.all, so total_count counts only the branches that appear.
completion_config |
Early exit completion_reason |
Full completion completion_reason |
|---|---|---|
all_successful() (default) |
FAILURE_TOLERANCE_EXCEEDED |
ALL_COMPLETED |
first_successful() |
MIN_SUCCESSFUL_REACHED |
ALL_COMPLETED |
all_completed() |
n/a | ALL_COMPLETED |
tolerated_failure_count=N |
FAILURE_TOLERANCE_EXCEEDED |
ALL_COMPLETED |
tolerated_failure_percentage=N |
FAILURE_TOLERANCE_EXCEEDED |
ALL_COMPLETED |
min_successful=N |
MIN_SUCCESSFUL_REACHED |
ALL_COMPLETED |
The default all_successful() fails the batch on the first branch failure. Use
CompletionConfig.all_completed() to run every branch regardless of failures.
Set should_complete when the threshold fields cannot express the rule. The predicate
receives a CompletionStatus (success_count, failure_count, completed_count,
total_count, and items, a per-branch tuple of CompletionItemStatus) and returns a
CompletionDecision: continue_batch() to keep going, or complete_batch(outcome) to
stop, where outcome defaults to CompletionOutcome.SUCCEEDED. A
CompletionOutcome.FAILED outcome marks the whole batch failed, and throw_if_error()
then raises BatchCompletionError even when no individual branch failed.
from aws_durable_execution_sdk_python import (
BatchResult,
CompletionStatus,
DurableContext,
complete_batch,
continue_batch,
durable_execution,
)
from aws_durable_execution_sdk_python.config import CompletionConfig, ParallelConfig
def try_primary(ctx: DurableContext) -> str:
return ctx.step(lambda _: "primary result", name="primary")
def try_secondary(ctx: DurableContext) -> str:
return ctx.step(lambda _: "secondary result", name="secondary")
def stop_after_first_success(status: CompletionStatus):
if status.success_count >= 1:
return complete_batch()
return continue_batch()
@durable_execution
def handler(event: dict, context: DurableContext) -> str | None:
config = ParallelConfig(
completion_config=CompletionConfig(should_complete=stop_after_first_success),
)
result: BatchResult[str] = context.parallel(
[try_primary, try_secondary],
name="fetch-data",
config=config,
)
results = result.get_results()
return results[0] if results else None
The predicate runs before any branch is scheduled (completed_count == 0) and again on
each terminal or suspension event, so it must handle the initial zero-progress
snapshot. It cannot be combined with min_successful, tolerated_failure_count, or
tolerated_failure_percentage, and must be deterministic, side-effect-free, and
monotonic. Unscheduled branches report status=None in items.
The ParallelResult's completionStatus indicates the stop condition with which the
parallel operation completed. All registered branches (including those never started)
are counted in size.
completionConfig |
Early exit completionStatus |
Full completion completionStatus |
|---|---|---|
allCompleted() (default) |
n/a | ALL_COMPLETED |
allSuccessful() |
FAILURE_TOLERANCE_EXCEEDED |
ALL_COMPLETED |
firstSuccessful() |
MIN_SUCCESSFUL_REACHED |
ALL_COMPLETED |
minSuccessful(N) |
MIN_SUCCESSFUL_REACHED |
ALL_COMPLETED |
toleratedFailureCount(N) |
FAILURE_TOLERANCE_EXCEEDED |
ALL_COMPLETED |
Note
ParallelConfig in Java does not support toleratedFailurePercentage. Use
toleratedFailureCount instead.
Use CompletionConfig.shouldComplete(...) when the predefined thresholds cannot
express the completion rule. The SDK evaluates the function as completion state
changes. It receives a CompletionStatus with successCount, failureCount,
completedCount, totalCount, and allItemsRegistered. For parallel operations,
allItemsRegistered becomes true when get() or close() joins the operation.
Return CompletionDecision.continueExecution() to keep processing. Return
CompletionDecision.complete(...) with CUSTOM_COMPLETION_SUCCEEDED or
CUSTOM_COMPLETION_FAILED to stop and classify the result.
var completion = CompletionConfig.shouldComplete(status -> {
if (status.successCount() >= requiredSuccesses) {
return CompletionConfig.CompletionDecision.complete(
ConcurrencyCompletionStatus.CUSTOM_COMPLETION_SUCCEEDED);
}
if (status.failureCount() >= failureLimit) {
return CompletionConfig.CompletionDecision.complete(
ConcurrencyCompletionStatus.CUSTOM_COMPLETION_FAILED);
}
return CompletionConfig.CompletionDecision.continueExecution();
});
A custom completion function is mutually exclusive with minSuccessful and
toleratedFailureCount. It must return a non-null decision. Keep it deterministic
and free of side effects. Registered branches that have not started when it
completes have status SKIPPED. CUSTOM_COMPLETION_FAILED does not throw
automatically. Inspect result.completionStatus().isSucceeded() to distinguish
the custom outcomes.
BatchResult.Reason records the stop condition. Branches that never started
are omitted from Items. A branch that started but did not complete appears
with BatchItemStarted. Parallel does not leave abandoned branches
running. An abandoned branch stops at its next durable operation. Parallel
returns only after every started branch has stopped.
CompletionConfig |
Early exit Reason |
Full completion Reason |
|---|---|---|
| zero value (default, fail-fast) | CompletionFailureToleranceExceeded |
CompletionAllCompleted |
ToleratedFailureCount: aws.Int(N) |
CompletionFailureToleranceExceeded |
CompletionAllCompleted |
ToleratedFailurePercentage: aws.Int(N) |
CompletionFailureToleranceExceeded |
CompletionAllCompleted |
MinSuccessful: N |
CompletionMinSuccessfulReached |
CompletionAllCompleted |
ShouldComplete: ... |
CompletionCustomSucceeded or CompletionCustomFailed |
CompletionAllCompleted |
The default is fail-fast. Set ShouldComplete when the threshold fields cannot
express the rule. The predicate receives a BatchProgress snapshot before the first
branch and again after each branch reaches a terminal state, so it must handle the
initial zero-progress snapshot. It must be deterministic. Return ContinueBatch(),
or CompleteBatch(durable.CompletionOutcomeSucceeded) or
CompleteBatch(durable.CompletionOutcomeFailed) to stop and classify the result.
With ShouldComplete set, a branch failure does not stop the batch by itself. A
failed custom outcome returns a *BatchError, or a *BatchCompletionError when no
branch failed. A predicate that panics fails the operation with an error that is not
a *BatchError.
// Package main stops a Parallel early with a custom completion decision once
// one branch succeeds.
package main
import "github.com/aws/aws-durable-execution-sdk-go/durable"
func handler(ctx durable.Context, _ any) (*string, error) {
result, err := durable.Parallel(ctx, "fetch-data", []durable.Branch[string]{
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "primary", func(durable.StepContext) (string, error) {
return "primary result", nil
})
}},
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "secondary", func(durable.StepContext) (string, error) {
return "secondary result", nil
})
}},
}, durable.WithCompletion(durable.CompletionConfig{
ShouldComplete: func(p durable.BatchProgress) durable.CompletionDecision {
if p.SuccessCount >= 1 {
return durable.CompleteBatch(durable.CompletionOutcomeSucceeded)
}
return durable.ContinueBatch()
},
}))
if err != nil {
return nil, err
}
results := result.Results()
if len(results) == 0 {
return nil, nil
}
return &results[0], nil
}
func main() { durable.Start(handler) }
The BatchResult's reason field records the stop condition. Branches that never
started are omitted from items. A branch that started but did not complete appears
with BatchItemStatus::Started. The parallel operation does not leave abandoned
branches running. The SDK cancels each one at its next .await, and none of its
later checkpoints is written.
CompletionConfig |
Early exit reason |
Full completion reason |
|---|---|---|
| none (default, fail-fast) | FailureToleranceExceeded |
AllCompleted |
with_tolerated_failure_count(n) |
FailureToleranceExceeded |
AllCompleted |
with_tolerated_failure_percentage(p) |
FailureToleranceExceeded |
AllCompleted |
with_min_successful(n) |
MinSuccessfulReached |
AllCompleted |
with_completion_predicate(...) |
CustomCompletionSucceeded or CustomCompletionFailed |
custom reason if it returns Complete; otherwise AllCompleted |
The default is fail-fast. Use with_completion_predicate when the thresholds cannot
express the rule. The predicate receives a BatchStats with succeeded(),
failed(), settled(), total_items(), and items(), one CompletionItem per
branch. Each item carries its zero-based index, caller-supplied name, and current
status. The predicate returns a CompletionDecision. Return
CompletionDecision::Continue to keep going, or
CompletionDecision::complete(CompletionOutcome::Succeeded) or
CompletionDecision::complete(CompletionOutcome::Failed) to stop and classify the
result. With a predicate set, a branch failure does not stop the batch by itself. A
Failed outcome makes .await return a ChildFailed error for the first failed
branch, or a BatchCompletionFailed error when no branch failed.
use aws_durable_execution_sdk as durable;
use durable::builders::map_parallel::{
BatchStats, CompletionConfig, CompletionDecision, CompletionOutcome,
};
async fn try_primary(ctx: durable::DurableContext) -> Result<String, durable::BoxError> {
Ok(ctx
.step(|_| async { Ok("primary result".to_owned()) })
.name("primary")
.await?)
}
async fn try_secondary(ctx: durable::DurableContext) -> Result<String, durable::BoxError> {
Ok(ctx
.step(|_| async { Ok("secondary result".to_owned()) })
.name("secondary")
.await?)
}
fn stop_after_first_success(stats: &BatchStats<'_>) -> CompletionDecision {
if stats.succeeded() >= 1 {
return CompletionDecision::complete(CompletionOutcome::Succeeded);
}
CompletionDecision::Continue
}
async fn handler(
_event: serde_json::Value,
ctx: durable::DurableContext,
) -> Result<Option<String>, durable::BoxError> {
let results = ctx
.parallel([
durable::Branch::unnamed(try_primary),
durable::Branch::unnamed(try_secondary),
])
.name("fetch-data")
.completion(CompletionConfig::with_completion_predicate(
stop_after_first_success,
))
.await?;
Ok(results.into_iter().next())
}
#[tokio::main]
async fn main() -> Result<(), lambda_runtime::Error> {
durable::init_default_subscriber()?;
durable::run(handler).await
}
The SDK calls the predicate before each branch starts and after each branch settles,
so it must handle the initial zero-progress snapshot. It must be a pure function of
the BatchStats it receives, and it must be monotonic. Once it returns Complete
with an outcome, it must return the same decision for every later snapshot. It
cannot be combined with the thresholds. A branch that is waiting to start has None
as its status in items().
The IBatchResult's CompletionReason indicates the stop condition with which the
parallel operation completed. Branches that were not dispatched before the operation
resolved appear in result.All with status Started.
CompletionConfig |
Early exit CompletionReason |
Full completion CompletionReason |
|---|---|---|
AllSuccessful() (default) |
FailureToleranceExceeded |
AllCompleted |
AllCompleted() |
n/a | AllCompleted |
FirstSuccessful() |
MinSuccessfulReached |
AllCompleted |
MinSuccessful = N |
MinSuccessfulReached |
AllCompleted |
ToleratedFailureCount = N |
FailureToleranceExceeded |
AllCompleted |
ToleratedFailurePercentage = N |
FailureToleranceExceeded |
AllCompleted |
When the operation resolves with FailureToleranceExceeded, awaiting it throws
ParallelException, which carries the aggregate result on Result.
Note
When using a minSuccessful strategy, failures do not trigger early exit. If all
branches fail before the success threshold is reached, the operation completes with
ALL_COMPLETED.
import {
BatchResult,
DurableContext,
withDurableExecution,
} from "@aws/durable-execution-sdk-js";
export const handler = withDurableExecution(
async (event: any, context: DurableContext): Promise<string | undefined> => {
// Complete as soon as one branch succeeds
const result: BatchResult<string> = await context.parallel(
"race",
[
async (ctx) => ctx.step("source-a", async () => "result from a"),
async (ctx) => ctx.step("source-b", async () => "result from b"),
async (ctx) => ctx.step("source-c", async () => "result from c"),
],
{ completionConfig: { minSuccessful: 1 } },
);
return result.getResults()[0];
},
);
from aws_durable_execution_sdk_python import (
BatchResult,
DurableContext,
durable_execution,
)
from aws_durable_execution_sdk_python.config import CompletionConfig, ParallelConfig
def source_a(ctx: DurableContext) -> str:
return ctx.step(lambda _: "result from a", name="source-a")
def source_b(ctx: DurableContext) -> str:
return ctx.step(lambda _: "result from b", name="source-b")
def source_c(ctx: DurableContext) -> str:
return ctx.step(lambda _: "result from c", name="source-c")
@durable_execution
def handler(event: dict, context: DurableContext) -> str | None:
result: BatchResult[str] = context.parallel(
[source_a, source_b, source_c],
name="race",
config=ParallelConfig(completion_config=CompletionConfig.first_successful()),
)
results = result.get_results()
return results[0] if results else None
import software.amazon.lambda.durable.DurableContext;
import software.amazon.lambda.durable.DurableHandler;
import software.amazon.lambda.durable.config.CompletionConfig;
import software.amazon.lambda.durable.config.ParallelConfig;
import software.amazon.lambda.durable.model.ParallelResult;
public class CompletionConfigExample extends DurableHandler<Void, ParallelResult> {
@Override
public ParallelResult handleRequest(Void input, DurableContext context) {
var config = ParallelConfig.builder()
.completionConfig(CompletionConfig.firstSuccessful())
.build();
try (var parallel = context.parallel("race", config)) {
parallel.branch("source-a", String.class,
ctx -> ctx.step("a", String.class, s -> "result from a"));
parallel.branch("source-b", String.class,
ctx -> ctx.step("b", String.class, s -> "result from b"));
parallel.branch("source-c", String.class,
ctx -> ctx.step("c", String.class, s -> "result from c"));
return parallel.get();
}
}
}
// Package main completes a Parallel as soon as one branch succeeds.
package main
import "github.com/aws/aws-durable-execution-sdk-go/durable"
func handler(ctx durable.Context, _ any) (*string, error) {
result, err := durable.Parallel(ctx, "race", []durable.Branch[string]{
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "source-a", func(durable.StepContext) (string, error) {
return "result from a", nil
})
}},
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "source-b", func(durable.StepContext) (string, error) {
return "result from b", nil
})
}},
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "source-c", func(durable.StepContext) (string, error) {
return "result from c", nil
})
}},
}, durable.WithCompletion(durable.CompletionConfig{MinSuccessful: 1}))
if err != nil {
return nil, err
}
results := result.Results()
if len(results) == 0 {
return nil, nil
}
return &results[0], nil
}
func main() { durable.Start(handler) }
use aws_durable_execution_sdk as durable;
use durable::builders::map_parallel::CompletionConfig;
async fn handler(
_event: serde_json::Value,
ctx: durable::DurableContext,
) -> Result<Option<String>, durable::BoxError> {
let results = ctx
.parallel([
durable::Branch::unnamed(|ctx| async move {
Ok(ctx
.step(|_| async { Ok("result from a".to_owned()) })
.name("source-a")
.await?)
}),
durable::Branch::unnamed(|ctx| async move {
Ok(ctx
.step(|_| async { Ok("result from b".to_owned()) })
.name("source-b")
.await?)
}),
durable::Branch::unnamed(|ctx| async move {
Ok(ctx
.step(|_| async { Ok("result from c".to_owned()) })
.name("source-c")
.await?)
}),
])
.name("race")
.completion(CompletionConfig::with_min_successful(1))
.await?;
Ok(results.into_iter().next())
}
#[tokio::main]
async fn main() -> Result<(), lambda_runtime::Error> {
durable::init_default_subscriber()?;
durable::run(handler).await
}
using Amazon.Lambda.Core;
using Amazon.Lambda.DurableExecution;
public class CompletionConfigExample
{
public Task<DurableExecutionInvocationOutput> Handler(
DurableExecutionInvocationInput input, ILambdaContext context)
=> DurableFunction.WrapAsync<object, string?>(Workflow, input, context);
private async Task<string?> Workflow(object input, IDurableContext ctx)
{
var config = new ParallelConfig
{
// Complete as soon as one branch succeeds
CompletionConfig = CompletionConfig.FirstSuccessful(),
};
IBatchResult<string> result = await ctx.ParallelAsync(
new Func<IDurableContext, CancellationToken, Task<string>>[]
{
async (branch, ct) => await branch.StepAsync(
async (_, _) => "result from a", name: "source-a"),
async (branch, ct) => await branch.StepAsync(
async (_, _) => "result from b", name: "source-b"),
async (branch, ct) => await branch.StepAsync(
async (_, _) => "result from c", name: "source-c"),
},
name: "race",
config: config);
return result.GetResults().FirstOrDefault();
}
}
Error handling¶
When a branch throws an error, parallel captures the error in the result rather than propagating it immediately. Other branches continue running.
BatchResult.status is FAILED if any branch failed. Call throwIfError() to
propagate the first branch error as an exception, or inspect getErrors() to handle
errors individually.
import {
BatchResult,
DurableContext,
withDurableExecution,
} from "@aws/durable-execution-sdk-js";
export const handler = withDurableExecution(
async (event: any, context: DurableContext) => {
const result: BatchResult<string> = await context.parallel(
"tasks",
[
async (ctx) => ctx.step("task-1", async () => "ok"),
async (ctx) =>
ctx.step("task-2", async () => {
throw new Error("task 2 failed");
}),
async (ctx) => ctx.step("task-3", async () => "ok"),
],
{ completionConfig: { toleratedFailureCount: 1 } },
);
return {
succeeded: result.successCount,
failed: result.failureCount,
results: result.getResults(),
errors: result.getErrors().map((e) => e.message),
};
},
);
BatchResult.status is FAILED if any branch failed. Call throw_if_error() to
propagate the first branch error as an exception, or inspect get_errors() to handle
errors individually.
from aws_durable_execution_sdk_python import (
BatchResult,
DurableContext,
durable_execution,
)
from aws_durable_execution_sdk_python.config import CompletionConfig, ParallelConfig
def task_1(ctx: DurableContext) -> str:
return ctx.step(lambda _: "ok", name="task-1")
def task_2(ctx: DurableContext) -> str:
def fail(_):
raise ValueError("task 2 failed")
return ctx.step(fail, name="task-2")
def task_3(ctx: DurableContext) -> str:
return ctx.step(lambda _: "ok", name="task-3")
@durable_execution
def handler(event: dict, context: DurableContext) -> dict:
result: BatchResult[str] = context.parallel(
[task_1, task_2, task_3],
name="tasks",
config=ParallelConfig(
completion_config=CompletionConfig(tolerated_failure_count=1)
),
)
return {
"succeeded": result.success_count,
"failed": result.failure_count,
"results": result.get_results(),
"errors": [e.message for e in result.get_errors()],
}
Check result.failed() > 0 (where result is a ParallelResult) to detect branch
failures. To propagate a branch error, call .get() on the DurableFuture<T> for that
branch to rethrow the original exception. This will throw
ParallelBranchFailedException if the SDK cannot reconstruct the original.
import software.amazon.lambda.durable.DurableContext;
import software.amazon.lambda.durable.DurableHandler;
import software.amazon.lambda.durable.config.CompletionConfig;
import software.amazon.lambda.durable.config.ParallelConfig;
import software.amazon.lambda.durable.model.ParallelResult;
public class ErrorHandling extends DurableHandler<Void, ParallelResult> {
@Override
public ParallelResult handleRequest(Void input, DurableContext context) {
var config = ParallelConfig.builder()
.completionConfig(CompletionConfig.toleratedFailureCount(1))
.build();
try (var parallel = context.parallel("tasks", config)) {
parallel.branch("task-1", String.class,
ctx -> ctx.step("task-1", String.class, s -> "ok"));
parallel.branch("task-2", String.class, ctx -> ctx.step("task-2", String.class, s -> {
throw new RuntimeException("task 2 failed");
}));
parallel.branch("task-3", String.class,
ctx -> ctx.step("task-3", String.class, s -> "ok"));
return parallel.get();
}
}
}
Parallel captures each branch error in the result. By default (fail-fast)
the first branch failure completes the batch. Branches still running are
abandoned, and branches not yet started never run. Parallel then returns
the populated result together with a *durable.BatchError. Match it with
errors.As. Tolerate failures to keep every branch running, then read the
failures from BatchResult.Errors() and BatchResult.Failed().
// Package main reads branch failures from a Parallel result. Tolerating a
// failure keeps every branch running so the result lists both outcomes.
package main
import (
"errors"
"github.com/aws/aws-durable-execution-sdk-go/durable"
"github.com/aws/aws-sdk-go-v2/aws"
)
type Output struct {
Succeeded int `json:"succeeded"`
Failed int `json:"failed"`
Results []string `json:"results"`
Errors []string `json:"errors"`
}
func handler(ctx durable.Context, _ any) (Output, error) {
result, err := durable.Parallel(ctx, "tasks", []durable.Branch[string]{
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "task-1", func(durable.StepContext) (string, error) {
return "ok", nil
})
}},
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "task-2", func(durable.StepContext) (string, error) {
return "", errors.New("task 2 failed")
})
}},
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "task-3", func(durable.StepContext) (string, error) {
return "ok", nil
})
}},
}, durable.WithCompletion(durable.CompletionConfig{ToleratedFailureCount: aws.Int(1)}))
if err != nil {
return Output{}, err
}
messages := make([]string, 0, result.FailureCount())
for _, e := range result.Errors() {
messages = append(messages, e.Error())
}
return Output{
Succeeded: result.SuccessCount(),
Failed: result.FailureCount(),
Results: result.Results(),
Errors: messages,
}, nil
}
func main() { durable.Start(handler) }
.await returns only the results of succeeded branches. It returns an error when
the failure tolerance is exceeded, which the default fail-fast configuration does
at the first branch failure. The SDK then cancels the branches still running and
never starts the branches not yet started. With a tolerance such as
with_tolerated_failure_count(1), .await skips the failed branches. To inspect
them, use .await_batch(), which returns the BatchResult. Call into_result() to
propagate the first branch error, or inspect errors() to handle errors
individually. A BatchError's message is the branch's recorded error message,
such as task 2 failed.
use aws_durable_execution_sdk as durable;
use durable::builders::map_parallel::CompletionConfig;
use serde::Serialize;
#[derive(Serialize)]
struct Summary {
succeeded: usize,
failed: usize,
results: Vec<String>,
errors: Vec<String>,
}
async fn handler(
_event: serde_json::Value,
ctx: durable::DurableContext,
) -> Result<Summary, durable::BoxError> {
let result = ctx
.parallel([
durable::Branch::unnamed(|ctx| async move {
Ok(ctx
.step(|_| async { Ok("ok".to_owned()) })
.name("task-1")
.await?)
}),
durable::Branch::unnamed(|ctx| async move {
Ok(ctx
.step(|_| async { Err("task 2 failed".into()) })
.name("task-2")
.await?)
}),
durable::Branch::unnamed(|ctx| async move {
Ok(ctx
.step(|_| async { Ok("ok".to_owned()) })
.name("task-3")
.await?)
}),
])
.name("tasks")
.completion(CompletionConfig::with_tolerated_failure_count(1))
.await_batch()
.await?;
Ok(Summary {
succeeded: result.success_count(),
failed: result.failure_count(),
results: result.results().cloned().collect(),
errors: result.errors().map(|e| e.message.to_owned()).collect(),
})
}
#[tokio::main]
async fn main() -> Result<(), lambda_runtime::Error> {
durable::init_default_subscriber()?;
durable::run(handler).await
}
IBatchResult.HasFailure is true if any branch failed. Call ThrowIfError() to
propagate the first branch error as a DurableExecutionException, or inspect
GetErrors() to handle errors individually.
using Amazon.Lambda.Core;
using Amazon.Lambda.DurableExecution;
public class ErrorHandlingExample
{
public Task<DurableExecutionInvocationOutput> Handler(
DurableExecutionInvocationInput input, ILambdaContext context)
=> DurableFunction.WrapAsync<object, TaskSummary>(Workflow, input, context);
private async Task<TaskSummary> Workflow(object input, IDurableContext ctx)
{
var config = new ParallelConfig
{
CompletionConfig = new CompletionConfig { ToleratedFailureCount = 1 },
};
IBatchResult<string> result = await ctx.ParallelAsync(
new Func<IDurableContext, CancellationToken, Task<string>>[]
{
async (branch, ct) => await branch.StepAsync(
async (_, _) => "ok", name: "task-1"),
async (branch, ct) => await branch.StepAsync<string>(
(_, _) => throw new InvalidOperationException("task 2 failed"),
name: "task-2"),
async (branch, ct) => await branch.StepAsync(
async (_, _) => "ok", name: "task-3"),
},
name: "tasks",
config: config);
// BatchResult captures branch failures instead of throwing. Inspect
// GetErrors() to handle them, or call ThrowIfError() to propagate.
return new TaskSummary(
Succeeded: result.SuccessCount,
Failed: result.FailureCount,
Results: result.GetResults(),
Errors: result.GetErrors().Select(e => e.Message).ToList());
}
}
public record TaskSummary(
int Succeeded,
int Failed,
IReadOnlyList<string> Results,
IReadOnlyList<string> Errors);
Checkpointing¶
Checkpoint behavior depends on the nesting type. In nested mode, each branch checkpoints
its result in a per-branch CONTEXT operation. In flat mode, the SDK omits that context
checkpoint and records the branch outcome with the parent parallel operation. Durable
operations inside a branch still checkpoint in both modes.
Branches that have not completed when the parallel operation reaches its completion criteria receive no further checkpoint updates. Unless noted otherwise, the language-specific details below describe nested mode.
The parent parallel operation also checkpoints the serialized BatchResult for
observability. On replay, the SDK deserializes the BatchResult directly from that
checkpoint.
For results over 256KB, the SDK cannot store the full BatchResult in the checkpoint.
Instead, the SDK reconstructs the BatchResult from the checkpointed results of the
individual branches. In that case, the checkpoint stores a compact JSON summary, which
is for observability only.
The default summary generator produces:
The parent parallel operation also checkpoints the serialized BatchResult for
observability. On replay, the SDK deserializes the BatchResult directly from that
checkpoint.
For results over 256KB, the SDK cannot store the full BatchResult in the checkpoint,
so it re-executes the branches to reconstruct it instead. In that case, the checkpoint
stores the output of summary_generator, which is for observability only.
The default summary generator produces:
{
"type": "ParallelResult",
"totalCount": 3,
"successCount": 2,
"failureCount": 1,
"startedCount": 0,
"completionReason": "ALL_COMPLETED",
"status": "FAILED"
}
When you pass a custom ParallelConfig without setting summary_generator, the SDK
checkpoints an empty string for large payloads.
SummaryGenerator is a callable protocol you can pass by setting summary_generator on
ParallelConfig:
The parent parallel operation checkpoints no result payload. On replay, the SDK always
re-executes the branches to reconstruct the ParallelResult from their individual
checkpoints.
WithNesting selects the checkpoint shape, as for Map. The SDK checkpoints
the whole BatchResult when it is at most 256KB serialized. On replay, the
SDK decodes that BatchResult without running the branches. A larger result
is not stored. The checkpoint then keeps the child operations plus a compact
record, and replay rebuilds each branch from that branch's own checkpoint.
The record holds type, totalCount, successCount, failureCount,
startedCount, completionReason, status, and itemStatuses, one
character per started branch. Pass WithBatchSummary to add your own string
under the summary key.
.nesting(...) selects the checkpoint shape, as for map. The SDK checkpoints the
whole batch result when it is at most 256KB serialized. On replay, the SDK reads
that result without running the branches. A larger result is not stored. The
checkpoint then holds a compact record. In NestingMode::Normal replay rebuilds
each branch from that branch's own checkpoint. In NestingMode::Flat replay runs
the branches again. The record holds type (ParallelResult), totalCount,
successCount, failureCount, startedCount, completionReason, status, and
itemStatuses, one character per started branch. Pass .summary(...) to add your
own string under the summary key. Replay reads itemStatuses and
completionReason. The other fields and summary are for observability only.
parallel_mixed writes the same record, and its .summary(...) adds the same
summary key. Its summary function receives a
BatchResult<durable::BranchValue>, and each durable::BranchValue hides its
branch's value. Take each branch's durable::BranchKey with BranchHandle::key,
move the keys into the summary function, and read each value with
BatchResult::value(&key). It returns None for a branch that failed, was still
running when the batch completed, or never started. The handles are empty while
the summary function runs.
In nested mode, the SDK reconstructs IBatchResult from per-branch checkpoints.
In flat mode, the SDK records branch results and errors inline on the parent parallel
operation instead. The SDK serializes results with the ILambdaSerializer registered
on ILambdaContext.Serializer.
Nesting parallel operations¶
A branch function can call context.parallel() to create nested parallel operations.
Each nested parallel creates its own set of child contexts.
import {
BatchResult,
DurableContext,
withDurableExecution,
} from "@aws/durable-execution-sdk-js";
export const handler = withDurableExecution(
async (event: any, context: DurableContext): Promise<string[][]> => {
const outer: BatchResult<string[]> = await context.parallel("outer", [
async (ctx) => {
const inner: BatchResult<string> = await ctx.parallel("inner-a", [
async (c) => c.step("a1", async () => "a1"),
async (c) => c.step("a2", async () => "a2"),
]);
return inner.getResults();
},
async (ctx) => {
const inner: BatchResult<string> = await ctx.parallel("inner-b", [
async (c) => c.step("b1", async () => "b1"),
async (c) => c.step("b2", async () => "b2"),
]);
return inner.getResults();
},
]);
return outer.getResults();
},
);
from aws_durable_execution_sdk_python import (
BatchResult,
DurableContext,
durable_execution,
)
def group_a(ctx: DurableContext) -> list[str]:
inner: BatchResult[str] = ctx.parallel(
[
lambda c: c.step(lambda _: "a1", name="a1"),
lambda c: c.step(lambda _: "a2", name="a2"),
],
name="inner-a",
)
return inner.get_results()
def group_b(ctx: DurableContext) -> list[str]:
inner: BatchResult[str] = ctx.parallel(
[
lambda c: c.step(lambda _: "b1", name="b1"),
lambda c: c.step(lambda _: "b2", name="b2"),
],
name="inner-b",
)
return inner.get_results()
@durable_execution
def handler(event: dict, context: DurableContext) -> list[list[str]]:
outer: BatchResult[list[str]] = context.parallel(
[group_a, group_b],
name="outer",
)
return outer.get_results()
import software.amazon.lambda.durable.DurableContext;
import software.amazon.lambda.durable.DurableHandler;
import software.amazon.lambda.durable.model.ParallelResult;
public class NestedParallel extends DurableHandler<Void, ParallelResult> {
@Override
public ParallelResult handleRequest(Void input, DurableContext context) {
try (var outer = context.parallel("outer")) {
outer.branch("group-a", ParallelResult.class, ctx -> {
try (var inner = ctx.parallel("inner-a")) {
inner.branch("a1", String.class, c -> c.step("a1", String.class, s -> "a1"));
inner.branch("a2", String.class, c -> c.step("a2", String.class, s -> "a2"));
return inner.get();
}
});
outer.branch("group-b", ParallelResult.class, ctx -> {
try (var inner = ctx.parallel("inner-b")) {
inner.branch("b1", String.class, c -> c.step("b1", String.class, s -> "b1"));
inner.branch("b2", String.class, c -> c.step("b2", String.class, s -> "b2"));
return inner.get();
}
});
return outer.get();
}
}
}
// Package main nests a Parallel inside a Parallel branch. Each nested
// Parallel creates its own set of child contexts.
package main
import "github.com/aws/aws-durable-execution-sdk-go/durable"
func handler(ctx durable.Context, _ any) ([][]string, error) {
result, err := durable.Parallel(ctx, "outer", []durable.Branch[[]string]{
{Func: func(ctx durable.Context) ([]string, error) {
inner, err := durable.Parallel(ctx, "inner-a", []durable.Branch[string]{
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "a1", func(durable.StepContext) (string, error) { return "a1", nil })
}},
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "a2", func(durable.StepContext) (string, error) { return "a2", nil })
}},
})
if err != nil {
return nil, err
}
return inner.Results(), nil
}},
{Func: func(ctx durable.Context) ([]string, error) {
inner, err := durable.Parallel(ctx, "inner-b", []durable.Branch[string]{
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "b1", func(durable.StepContext) (string, error) { return "b1", nil })
}},
{Func: func(ctx durable.Context) (string, error) {
return durable.Step(ctx, "b2", func(durable.StepContext) (string, error) { return "b2", nil })
}},
})
if err != nil {
return nil, err
}
return inner.Results(), nil
}},
})
if err != nil {
return nil, err
}
return result.Results(), nil
}
func main() { durable.Start(handler) }
use aws_durable_execution_sdk as durable;
async fn handler(
_event: serde_json::Value,
ctx: durable::DurableContext,
) -> Result<Vec<Vec<String>>, durable::BoxError> {
let outer = ctx
.parallel([
durable::Branch::unnamed(|ctx| async move {
let inner = ctx
.parallel([
durable::Branch::unnamed(|c| async move {
Ok(c.step(|_| async { Ok("a1".to_owned()) }).name("a1").await?)
}),
durable::Branch::unnamed(|c| async move {
Ok(c.step(|_| async { Ok("a2".to_owned()) }).name("a2").await?)
}),
])
.name("inner-a")
.await?;
Ok(inner)
}),
durable::Branch::unnamed(|ctx| async move {
let inner = ctx
.parallel([
durable::Branch::unnamed(|c| async move {
Ok(c.step(|_| async { Ok("b1".to_owned()) }).name("b1").await?)
}),
durable::Branch::unnamed(|c| async move {
Ok(c.step(|_| async { Ok("b2".to_owned()) }).name("b2").await?)
}),
])
.name("inner-b")
.await?;
Ok(inner)
}),
])
.name("outer")
.await?;
Ok(outer)
}
#[tokio::main]
async fn main() -> Result<(), lambda_runtime::Error> {
durable::init_default_subscriber()?;
durable::run(handler).await
}
using Amazon.Lambda.Core;
using Amazon.Lambda.DurableExecution;
public class NestedParallelExample
{
public Task<DurableExecutionInvocationOutput> Handler(
DurableExecutionInvocationInput input, ILambdaContext context)
=> DurableFunction.WrapAsync<object, IReadOnlyList<IReadOnlyList<string>>>(
Workflow, input, context);
private async Task<IReadOnlyList<IReadOnlyList<string>>> Workflow(
object input, IDurableContext ctx)
{
IBatchResult<IReadOnlyList<string>> outer = await ctx.ParallelAsync(
new Func<IDurableContext, CancellationToken, Task<IReadOnlyList<string>>>[]
{
async (branch, ct) =>
{
// A branch can call ParallelAsync to nest parallel operations.
IBatchResult<string> inner = await branch.ParallelAsync(
new Func<IDurableContext, CancellationToken, Task<string>>[]
{
async (c, t) => await c.StepAsync(async (_, _) => "a1", name: "a1"),
async (c, t) => await c.StepAsync(async (_, _) => "a2", name: "a2"),
},
name: "inner-a");
return inner.GetResults();
},
async (branch, ct) =>
{
IBatchResult<string> inner = await branch.ParallelAsync(
new Func<IDurableContext, CancellationToken, Task<string>>[]
{
async (c, t) => await c.StepAsync(async (_, _) => "b1", name: "b1"),
async (c, t) => await c.StepAsync(async (_, _) => "b2", name: "b2"),
},
name: "inner-b");
return inner.GetResults();
},
},
name: "outer");
return outer.GetResults();
}
}
See also¶
- Map operations run the same function concurrently on a collection
- Child contexts understand child context isolation
- Steps use steps within parallel branches
- Error handling in durable functions
Checkpoint consumption
Durable operations consume checkpoints. To understand how this operation affects your checkpoint usage, see Checkpoint consumption.