aws_durable_execution_sdk/future.rs
1//! Future types for durable operations.
2//!
3//! [`DurableFuture`] is the uniform handle for all durable operation
4//! results. [`Branch`] defines a named parallel branch, and [`BranchSet`]
5//! a set of branches with different result types whose results each
6//! [`BranchHandle`] returns. [`Callback`] holds a callback token and its
7//! result future.
8
9use std::future::Future;
10use std::marker::PhantomData;
11use std::pin::Pin;
12use std::sync::Arc;
13use std::sync::atomic::{AtomicBool, Ordering};
14use std::task::{Context, Poll};
15
16use crate::coordinator::InvocationCoordinator;
17
18use crate::BoxError;
19use crate::DurableContext;
20use crate::error::{ChildFnError, OperationError};
21
22/// The uniform future handle for all durable operations.
23///
24/// Every builder state that implements
25/// [`IntoFuture`](std::future::IntoFuture) targets `DurableFuture<O>`. A
26/// `wait_for_condition` builder implements it only once a wait strategy is
27/// set. Every operation except a combinator and a
28/// [`DurableContext::with_retry`] block has already claimed its operation
29/// ID when its builder was created. A `with_retry` block claims its ID when
30/// the builder becomes this future. A combinator
31/// ([`DurableContext::try_join_all`], [`DurableContext::join_all`],
32/// [`DurableContext::select_ok`] and [`DurableContext::race`]) claims its ID
33/// on the first poll of this future, or at `.spawn()`. A combinator future
34/// that is dropped before its first poll claims no ID and records nothing.
35/// A combinator future passed to another combinator must already have
36/// claimed its ID: start it with `.spawn()` and pass the returned handle. A
37/// still-unclaimed one fails the execution with a context usage error. The
38/// body runs when polled (lazy) unless the builder was terminated with
39/// `.spawn()` (eager).
40///
41/// When produced by `.spawn()`, `.spawn_batch()` or
42/// [`Callback::spawn_result`], the operation runs eagerly on its own SDK
43/// task. Dropping the `DurableFuture` loses only the result: the operation
44/// keeps running until it settles, its scope closes or the invocation ends.
45/// An operation that settles records its outcome and fires its plugin
46/// hooks. Its error goes into its record and is returned to nobody, and a
47/// panic in it fails the invocation. A running detached operation keeps the
48/// invocation from suspending, and one that waits only on the service lets
49/// it suspend. When the handler returns, the invocation ends and stops each
50/// detached operation that still runs. A stopped operation fires no end
51/// hook. Its record, if it has one, keeps the last state written, which can
52/// be `STARTED`, and the execution can end with the handler's result.
53///
54/// The SDK stops work in three cases:
55///
56/// - a combinator stops the `.future()` inputs it started that are still
57/// running when it resolves, and lets an input started with `.spawn()`
58/// run;
59/// - a closed scope stops the work still running inside it. A scope closes
60/// when a child context's body returns, when a `with_retry` block with
61/// its own record ends, when an attempt of any `with_retry` block ends,
62/// and when a `map`, `parallel` or
63/// `parallel_mixed` item, or the whole batch, completes;
64/// - the end of the invocation stops all remaining operation work.
65///
66/// A stopped task stops at its next `.await`, and its record can stay
67/// `STARTED`. The SDK cannot stop code between two `.await`s,
68/// `spawn_blocking` work, tasks or threads the handler starts itself, or a
69/// request already sent to another service.
70///
71/// An operation that waits on the service (a wait, a callback result, an
72/// invoke) stays pending while other SDK work runs, and continues in the
73/// same invocation when a checkpoint response completes it. The invocation
74/// suspends only when no SDK work can make progress and an operation
75/// waits.
76///
77/// # Examples
78///
79/// ```no_run
80/// use aws_durable_execution_sdk as durable;
81/// use aws_durable_execution_sdk::DurableFuture;
82///
83/// async fn handler(
84/// _event: serde_json::Value,
85/// ctx: durable::DurableContext,
86/// ) -> Result<(), durable::BoxError> {
87/// // DurableFuture implements Future
88/// let future: DurableFuture<i32> = ctx.step(|_| async { Ok(42) }).future();
89/// let value: i32 = future.await?;
90/// assert_eq!(value, 42);
91/// Ok(())
92/// }
93/// ```
94#[must_use = "futures do nothing unless polled or spawned"]
95#[non_exhaustive]
96pub struct DurableFuture<O> {
97 inner: Pin<Box<dyn Future<Output = Result<O, OperationError>> + Send>>,
98 /// The first-poll flag of an operation started on its own task, with
99 /// the coordinator to notify when the handle is first polled. `None`
100 /// for every other handle, and after the first poll.
101 awaited: Option<(Arc<AtomicBool>, Arc<InvocationCoordinator>)>,
102 /// The pending claim of a combinator that has not claimed its operation
103 /// ID yet. `None` for every other future, and once the claim ran. While
104 /// it is `Some`, `inner` is a placeholder that is never polled.
105 claim: Option<PendingClaim<O>>,
106 /// The task context captured when the operation was created: the
107 /// frames of its context and the span current at the call. A task that
108 /// runs this future runs inside it, whoever starts the task.
109 task_cx: crate::task::TaskContext,
110 /// The start step of a lazy operation whose execution begins with one
111 /// (see [`crate::start`]): it runs the start step and returns the rest
112 /// of the operation. `None` for every other future, and once it ran.
113 /// While it is `Some`, `inner` is a placeholder that is never polled.
114 begin: Option<BeginFn<O>>,
115 /// Whether a combinator begins this future by polling it once on its
116 /// own task: a lazy invoke or `wait_for_condition`, whose first poll
117 /// serializes its input before it can queue its `START`.
118 first_poll_start: bool,
119 /// The ownership gate of an operation future: the context whose owner
120 /// may poll it. `None` for a future that executes nothing of its own:
121 /// a spawned handle, a settled callback result, an error future, and a
122 /// combinator until it claims its ID. Boxed, so the gate adds one
123 /// pointer to every future.
124 gate: Option<Box<PollGate>>,
125}
126
127/// The ownership gate of one operation future (see [`DurableFuture`]).
128///
129/// Every poll checks ownership, before the operation checks admission: an
130/// abandoned scope makes the operation pend, so a later check would never
131/// run for a future its owner sent out unpolled. The gate keeps no
132/// identity of an earlier poller, because Tokio may give a new task the ID
133/// of a task that exited, and a cached ID would then admit a task the
134/// invocation does not own. So a future that its owner polled until it
135/// suspended and then moved to such a task fails the execution when that
136/// task resumes it. The check costs the owner comparison and, for a task
137/// other than the owner, one lookup in the set of tasks the SDK started.
138struct PollGate {
139 ctx: DurableContext,
140}
141
142impl PollGate {
143 fn new(ctx: &DurableContext) -> Self {
144 Self { ctx: ctx.clone() }
145 }
146
147 /// Admits the current poll when the calling task or thread owns the
148 /// context. A refused poll has recorded the fatal context usage error.
149 fn admit(&mut self) -> Result<(), OperationError> {
150 self.ctx.enforce_task_ownership()
151 }
152}
153
154/// The start step of a lazy operation, and the builder of its remainder.
155type BeginFn<O> =
156 Box<dyn FnOnce() -> Pin<Box<dyn Future<Output = Result<O, OperationError>> + Send>> + Send>;
157
158/// The claim a combinator future runs on its first poll or at `.spawn()`.
159///
160/// `run` claims the combinator's operation ID on the context the
161/// combinator was created on, checks the claimed ID against the recorded
162/// history, and returns the future that runs the combinator.
163pub(crate) struct PendingClaim<O> {
164 /// The combinator's public method, such as `"race"`.
165 method: &'static str,
166 /// The display name of the context the combinator was created on:
167 /// `"root"` or the positional ID of the operation that created it.
168 context: String,
169 /// Claims the ID and builds the combinator's future.
170 run: Box<dyn FnOnce() -> DurableFuture<O> + Send>,
171}
172
173impl<O> PendingClaim<O> {
174 /// Creates the pending claim of combinator `method` created on the
175 /// context whose display name is `context`.
176 pub(crate) fn new(
177 method: &'static str,
178 context: String,
179 run: impl FnOnce() -> DurableFuture<O> + Send + 'static,
180 ) -> Self {
181 Self {
182 method,
183 context,
184 run: Box::new(run),
185 }
186 }
187}
188
189impl<O> std::fmt::Debug for DurableFuture<O> {
190 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
191 f.debug_struct("DurableFuture").finish_non_exhaustive()
192 }
193}
194
195impl<O: Send + 'static> DurableFuture<O> {
196 /// Creates a `DurableFuture` from an async computation.
197 pub(crate) fn from_async<F>(fut: F) -> Self
198 where
199 F: Future<Output = Result<O, OperationError>> + Send + 'static,
200 {
201 Self {
202 inner: Box::pin(fut),
203 awaited: None,
204 claim: None,
205 task_cx: crate::task::TaskContext::none(),
206 begin: None,
207 first_poll_start: false,
208 gate: None,
209 }
210 }
211
212 /// Maps the output and keeps the task context, so a
213 /// task that later runs the mapped future runs it inside the frames
214 /// and span of the operation's creation, as for the unmapped future.
215 pub(crate) fn map_output<T, M>(self, map: M) -> DurableFuture<T>
216 where
217 T: Send + 'static,
218 M: FnOnce(Result<O, OperationError>) -> Result<T, OperationError> + Send + 'static,
219 {
220 let Self {
221 inner,
222 awaited,
223 claim,
224 task_cx,
225 begin,
226 first_poll_start,
227 gate,
228 } = self;
229 match claim {
230 // An unclaimed combinator stays unclaimed: the mapped future
231 // keeps a pending claim that claims the ID and maps the claimed
232 // future, so `claim_now` takes the claimed future's context.
233 Some(claim) => {
234 let PendingClaim {
235 method,
236 context,
237 run,
238 } = claim;
239 DurableFuture::deferred(PendingClaim::new(method, context, move || {
240 run().map_output(map)
241 }))
242 }
243 // A lazy operation stays lazy: the mapped future keeps the
244 // start step, and maps the remainder the start step returns.
245 None => match begin {
246 Some(begin) => DurableFuture {
247 inner: Box::pin(std::future::pending()),
248 awaited,
249 claim: None,
250 task_cx,
251 begin: Some(Box::new(move || {
252 let rest = begin();
253 Box::pin(async move { map(rest.await) })
254 })),
255 first_poll_start,
256 gate,
257 },
258 None => DurableFuture {
259 inner: Box::pin(async move { map(inner.await) }),
260 awaited,
261 claim: None,
262 task_cx,
263 begin: None,
264 first_poll_start,
265 gate,
266 },
267 },
268 }
269 }
270
271 /// Creates the future of a combinator that claims its operation ID on
272 /// its first poll or at `.spawn()`, through [`Self::claim_now`].
273 pub(crate) fn deferred(claim: PendingClaim<O>) -> Self {
274 Self {
275 // A placeholder: `claim_now` replaces it before the first poll.
276 inner: Box::pin(std::future::pending()),
277 awaited: None,
278 claim: Some(claim),
279 task_cx: crate::task::TaskContext::none(),
280 begin: None,
281 first_poll_start: false,
282 gate: None,
283 }
284 }
285
286 /// Runs the pending claim of a combinator future: claims its operation
287 /// ID and checks it against the recorded history.
288 ///
289 /// The first poll and `.spawn()` call this. It runs the claim once. It
290 /// does nothing for a future that is not a combinator, and for a
291 /// combinator that already claimed.
292 pub(crate) fn claim_now(&mut self) {
293 if let Some(claim) = self.claim.take() {
294 let claimed = (claim.run)();
295 self.inner = claimed.inner;
296 self.task_cx = claimed.task_cx;
297 self.gate = claimed.gate;
298 }
299 }
300
301 /// Reports whether this future is a combinator that has not claimed its
302 /// operation ID yet.
303 pub(crate) fn is_unclaimed_combinator(&self) -> bool {
304 self.claim.is_some()
305 }
306
307 /// The message of the context usage error an outer combinator records
308 /// when it would start this still-unclaimed combinator as an input.
309 /// `None` when this future is not an unclaimed combinator.
310 ///
311 /// `outer` is the positional ID of the outer combinator.
312 pub(crate) fn unclaimed_input_message(&self, outer: &str) -> Option<String> {
313 self.claim.as_ref().map(|claim| {
314 format!(
315 "context usage error in \"{method}\": the combinator was created on context \
316 \"{context}\", but combinator \"{outer}\" started it as an input. Start the \
317 inner combinator with .spawn() and pass the returned handle to the outer \
318 combinator.",
319 method = claim.method,
320 context = claim.context,
321 )
322 })
323 }
324
325 /// Creates the future of one operation created on `ctx`.
326 ///
327 /// When one of the context's owners is abandoned before the first poll,
328 /// `fut` is never polled and the future never resolves (see
329 /// [`crate::checkpoint_coalescer::Admission`]). Every builder terminal,
330 /// awaited or spawned, passes here before its operation runs.
331 pub(crate) fn for_operation<F>(ctx: &DurableContext, fut: F) -> Self
332 where
333 F: Future<Output = Result<O, OperationError>> + Send + 'static,
334 {
335 let gate = ctx.clone();
336 let mut future = Self::from_async(async move {
337 gate.admit_operation().await;
338 drop(gate);
339 fut.await
340 });
341 future.task_cx = crate::task::TaskContext::current();
342 future.gate = Some(Box::new(PollGate::new(ctx)));
343 future
344 }
345
346 /// The task context captured when the operation was created.
347 pub(crate) fn task_context(&self) -> crate::task::TaskContext {
348 self.task_cx.clone()
349 }
350
351 /// Creates the future of one operation whose start step already ran on
352 /// the caller's task (see [`crate::start`]): `fut` is the rest of the
353 /// operation.
354 ///
355 /// It captures the task context current at the call, as
356 /// [`Self::for_operation`] does.
357 pub(crate) fn for_started_operation<F>(ctx: &DurableContext, fut: F) -> Self
358 where
359 F: Future<Output = Result<O, OperationError>> + Send + 'static,
360 {
361 let mut future = Self::from_async(fut);
362 future.task_cx = crate::task::TaskContext::current();
363 future.gate = Some(Box::new(PollGate::new(ctx)));
364 future
365 }
366
367 /// Creates the lazy future of one operation whose execution begins with
368 /// the start step (see [`crate::start`]): a step, a wait, a child
369 /// context, `with_retry`, a map, a parallel, a `parallel_mixed`, a
370 /// `create_callback` or a `wait_for_callback`.
371 ///
372 /// `begin` runs the start step and returns the rest of the operation.
373 /// It runs on the first poll, in the poller's context, or earlier when a
374 /// combinator begins the future as an input, in the creator's context
375 /// ([`Self::begin_in_creator_context`]). The start step checks
376 /// admission itself before it queues anything, so this adds no
377 /// admission gate of its own, unlike [`Self::for_operation`].
378 pub(crate) fn for_start_step<F>(
379 ctx: &DurableContext,
380 begin: impl FnOnce() -> F + Send + 'static,
381 ) -> Self
382 where
383 F: Future<Output = Result<O, OperationError>> + Send + 'static,
384 {
385 Self {
386 // A placeholder: `begin_now` replaces it before the first poll.
387 inner: Box::pin(std::future::pending()),
388 awaited: None,
389 claim: None,
390 begin: Some(Box::new(move || Box::pin(begin()))),
391 first_poll_start: false,
392 task_cx: crate::task::TaskContext::current(),
393 gate: Some(Box::new(PollGate::new(ctx))),
394 }
395 }
396
397 /// Runs the start step of a lazy operation now, on the calling task,
398 /// in the caller's context: the first poll calls this, so an operation
399 /// awaited directly runs both its start step and its body in its
400 /// awaiter's frames and span (#126 rule 5.2).
401 ///
402 /// It runs the start step once, and does nothing for a future without
403 /// one.
404 fn begin_now(&mut self) {
405 if let Some(begin) = self.begin.take() {
406 self.inner = begin();
407 }
408 }
409
410 /// Runs the start step of a lazy combinator input now, on the calling
411 /// task, inside the task context captured at the operation's creation:
412 /// its frames and its span. So `on_operation_start` and the start step
413 /// see the creator's context when a combinator created elsewhere begins
414 /// the input, as the input's remainder does on the task the combinator
415 /// spawns with that context (#126 rule 5.2).
416 ///
417 /// Only a combinator that begins its inputs calls this. It runs the
418 /// start step once, and does nothing for a future without one.
419 pub(crate) fn begin_in_creator_context(&mut self) {
420 if let Some(begin) = self.begin.take() {
421 self.inner = self.task_cx.enter(begin);
422 }
423 }
424
425 /// Creates the future of a lazy invoke or `wait_for_condition` on
426 /// `ctx`, as [`Self::for_operation`] does. A combinator begins such an
427 /// input by polling it once on its own task, because its first poll
428 /// serializes its input before it can queue its `START`.
429 pub(crate) fn for_first_poll_operation<F>(ctx: &DurableContext, fut: F) -> Self
430 where
431 F: Future<Output = Result<O, OperationError>> + Send + 'static,
432 {
433 let mut future = Self::for_operation(ctx, fut);
434 future.first_poll_start = true;
435 future
436 }
437
438 /// Reports whether a combinator begins this future by polling it once
439 /// on its own task (see [`Self::for_first_poll_operation`]).
440 pub(crate) fn starts_on_first_poll(&self) -> bool {
441 self.first_poll_start
442 }
443
444 /// Spawns the operation future on its own task, blessed in the task
445 /// ownership of `ctx` before its first poll.
446 ///
447 /// The task starts through the task gateway
448 /// ([`crate::task::spawn_tracked`]) and holds a permit of the
449 /// invocation's coordinator whenever it can make progress, so the
450 /// invocation does not suspend while it runs. A wait inside it registers
451 /// like any other wait. The task is registered with the scopes of `ctx`
452 /// (see [`crate::checkpoint_coalescer::Admission`]), so it stops when
453 /// one of them closes. Dropping the returned future loses only the
454 /// result: the task keeps running. A caller that does not own the
455 /// context fails the execution with a context usage error, no task
456 /// starts, and a combinator claims no ID. Otherwise a combinator claims
457 /// its ID here, before its task starts. A panic in the operation resumes on
458 /// the task that awaits the handle, with its original payload, and
459 /// fails the invocation when nothing awaits it. When the invocation
460 /// coordinator was created without a Tokio runtime, the returned future
461 /// resolves to an error and the operation records nothing.
462 ///
463 /// `awaited` is the first-poll flag the operation's wait registrations
464 /// carry. The returned handle sets it on its first poll and asks the
465 /// coordinator to arm those registrations' refreshes (see
466 /// [`crate::coordinator`]).
467 pub(crate) fn spawn_blessed(
468 mut future: Self,
469 ctx: &DurableContext,
470 awaited: Option<Arc<AtomicBool>>,
471 ) -> Self {
472 // The ownership check runs before a combinator's pending claim, so
473 // a refused `.spawn()` records the error of method `spawn` rather
474 // than the claim's, and the combinator claims no ID.
475 if let Some(refused) = Self::refuse_foreign_spawn(ctx) {
476 return refused;
477 }
478 future.claim_now();
479 let coordinator = ctx.coordinator();
480 let task_cx = future.task_context();
481 match crate::task::spawn_tracked(task_cx.clone(), coordinator, ctx.task_ownership(), future)
482 {
483 Ok(task) => {
484 if let Some(abort) = task.abort_handle() {
485 ctx.admission().register_task(ctx.owners(), abort);
486 }
487 let mut handle = Self::from_async(async move { task.await.into_value() });
488 handle.awaited = awaited.map(|flag| (flag, Arc::clone(coordinator)));
489 // The handle keeps the operation's context. A combinator
490 // that takes it spawns its input task with that context, so
491 // the input runs inside the creator's frames and span.
492 handle.task_cx = task_cx;
493 handle
494 }
495 // The invocation coordinator was created without a Tokio runtime:
496 // the operation records nothing and resolves to an error.
497 Err(no_runtime) => {
498 Self::from_async(
499 async move { Err(crate::task::NoRuntime::operation_error(no_runtime)) },
500 )
501 }
502 }
503 }
504
505 /// Builds the operation future with `build` and spawns it as
506 /// [`Self::spawn_blessed`] describes, for an operation whose `.spawn()`
507 /// runs no start step on the caller's task.
508 ///
509 /// The task-ownership check runs before `build`: building an invoke or
510 /// a `wait_for_condition` future runs its replay identity preflight,
511 /// which records a fatal error on a mismatch, and the first fatal error
512 /// wins. So a caller that does not own the context fails the execution
513 /// with the error of method `spawn`, and `build` is not called.
514 pub(crate) fn spawn_built(
515 ctx: &DurableContext,
516 awaited: Option<Arc<AtomicBool>>,
517 build: impl FnOnce() -> Self,
518 ) -> Self {
519 if let Some(refused) = Self::refuse_foreign_spawn(ctx) {
520 return refused;
521 }
522 Self::spawn_blessed(build(), ctx, awaited)
523 }
524
525 /// Starts an operation whose JS form begins inside the call: runs its
526 /// start step on the caller's task, then spawns the rest of it.
527 ///
528 /// The task-ownership check runs first: a caller that does not own the
529 /// context fails the execution, `start` is not called, and nothing is
530 /// queued. The runtime check runs next: when the invocation coordinator
531 /// was created without a Tokio runtime, the returned future resolves to
532 /// an error, `start` is not called, and nothing is queued. Otherwise `start` builds the
533 /// operation future after it ran the start step (see [`crate::start`])
534 /// on this task: the admission check, the task-ownership check, and the
535 /// `START` the
536 /// operation's record requires, with the start hook its JS order fires
537 /// at the call. Then the future runs on its own task, as
538 /// [`Self::spawn_blessed`] describes.
539 pub(crate) fn spawn_started(
540 ctx: &DurableContext,
541 awaited: Option<Arc<AtomicBool>>,
542 start: impl FnOnce() -> Self,
543 ) -> Self {
544 // The task-ownership check runs first: before the runtime check, so
545 // a thread with no runtime is refused rather than told it has none,
546 // and before the admission check and the builder's replay identity
547 // preflight, so a caller that does not own the context fails the
548 // execution in an abandoned owner and when the record also
549 // contradicts the operation.
550 if let Some(refused) = Self::refuse_foreign_spawn(ctx) {
551 return refused;
552 }
553 if let Err(no_runtime) = crate::task::task_runtime(ctx.coordinator()).map(drop) {
554 return Self::from_async(async move {
555 Err(crate::task::NoRuntime::operation_error(no_runtime))
556 });
557 }
558 Self::spawn_blessed(start(), ctx, awaited)
559 }
560
561 /// Refuses a `.spawn()` from a task or thread that does not own `ctx`:
562 /// records the fatal context usage error for method `spawn` and returns
563 /// a handle that resolves to an error. No task starts, so the operation
564 /// takes no permit and its body never runs. Returns `None` for a caller
565 /// that owns the context.
566 fn refuse_foreign_spawn(ctx: &DurableContext) -> Option<Self> {
567 let reason = ctx.task_ownership().check_current_task().err()?;
568 ctx.coordinator().record_fatal(
569 "Error".to_owned(),
570 crate::context::foreign_caller_message("spawn"),
571 );
572 Some(Self::from_async(async move {
573 Err(OperationError::from_kind(
574 crate::error::OperationErrorKind::Step(crate::error::StepError::new(
575 crate::error::StepErrorKind::ExecutionFailed,
576 Some(reason.into()),
577 )),
578 ))
579 }))
580 }
581}
582
583impl<O: Send + 'static> Future for DurableFuture<O> {
584 type Output = Result<O, OperationError>;
585
586 fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
587 // The first poll of a combinator claims its operation ID.
588 self.claim_now();
589 // Every poll checks ownership before the operation checks
590 // admission.
591 if let Some(gate) = self.gate.as_mut()
592 && let Err(refused) = gate.admit()
593 {
594 return Poll::Ready(Err(refused));
595 }
596 // The first poll of a lazy operation runs its start step, unless a
597 // combinator ran it already.
598 self.begin_now();
599 // The first poll of the handle of an operation started on its own
600 // task: from now on the scheduler refreshes its registrations.
601 if let Some((flag, coordinator)) = self.awaited.take() {
602 flag.store(true, Ordering::SeqCst);
603 coordinator.notify_awaited();
604 }
605 self.inner.as_mut().poll(cx)
606 }
607}
608
609// DurableFuture<O> is automatically Send when O: Send, since it only
610// contains a pinned boxed future that is Send when O: Send.
611
612/// A branch for [`DurableContext::parallel`].
613///
614/// Each branch defines an optional name and an async closure that receives
615/// a child [`DurableContext`]. History records the name, or
616/// `parallel-branch-{index}` when the branch has no name or an empty one.
617///
618/// # Examples
619///
620/// ```no_run
621/// use aws_durable_execution_sdk::{Branch, DurableContext};
622///
623/// let branch = Branch::new("process-a", |ctx: DurableContext| async move {
624/// let v = ctx.step(|_| async { Ok(1) }).await?;
625/// Ok(v)
626/// });
627/// # drop(branch);
628/// ```
629#[non_exhaustive]
630pub struct Branch<O> {
631 name: Option<String>,
632 body: BranchBody<O>,
633}
634
635/// The erased body of one parallel branch (crate-internal).
636///
637/// Branch bodies are inherently heterogeneous: every `Branch::new` call
638/// site captures a different closure and future type, and they are all
639/// collected into one `Vec`, so exactly ONE erasure per branch is
640/// unavoidable. This type keeps it to exactly one: the user's closure and
641/// its future live UNERASED inside a single boxed future built at
642/// [`Branch::new`]. The child [`DurableContext`] is not known until the
643/// batch coordinator dispatches the branch, so it is delivered through a
644/// oneshot channel the body awaits on first poll. There is no nested
645/// closure-box-returning-future-box layering: polling a running branch goes
646/// through one vtable hop.
647pub(crate) struct BranchBody<O> {
648 /// Delivers the child context to the body. The coordinator sends the
649 /// context BEFORE first polling `future`, so the body's receive
650 /// resolves immediately on first poll.
651 ctx_tx: tokio::sync::oneshot::Sender<DurableContext>,
652 /// The single erased branch future: awaits the child context, then runs
653 /// the user's factory closure and its future in place.
654 future: Pin<Box<dyn Future<Output = Result<O, ChildFnError>> + Send>>,
655}
656
657impl<O> BranchBody<O> {
658 /// Injects the child context and returns the branch future, ready to
659 /// poll. Called exactly once by the batch coordinator at dispatch time.
660 pub(crate) fn start(
661 self,
662 ctx: DurableContext,
663 ) -> Pin<Box<dyn Future<Output = Result<O, ChildFnError>> + Send>> {
664 // Send cannot fail: the receiver lives inside `self.future`, which
665 // we hold. Ignore the impossible error rather than panicking.
666 let _ = self.ctx_tx.send(ctx);
667 self.future
668 }
669}
670
671impl<O> std::fmt::Debug for Branch<O> {
672 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
673 f.debug_struct("Branch")
674 .field("name", &self.name)
675 .finish_non_exhaustive()
676 }
677}
678
679impl<O: Send + 'static> Branch<O> {
680 /// Creates a new named branch.
681 ///
682 /// The factory function receives a child [`DurableContext`] and returns
683 /// a future producing the branch result. The factory is not invoked
684 /// here: it runs when the parallel operation dispatches the branch.
685 ///
686 /// History records `name`. An empty name records
687 /// `parallel-branch-{index}`, and a completion predicate sees
688 /// `Some("")`.
689 ///
690 /// # Examples
691 ///
692 /// ```no_run
693 /// use aws_durable_execution_sdk::{Branch, DurableContext};
694 ///
695 /// let branch: Branch<i32> = Branch::new("my-branch", |_ctx: DurableContext| async move {
696 /// Ok(42)
697 /// });
698 /// # drop(branch);
699 /// ```
700 pub fn new<F, Fut>(name: impl Into<String>, factory: F) -> Self
701 where
702 F: FnOnce(DurableContext) -> Fut + Send + 'static,
703 Fut: Future<Output = Result<O, BoxError>> + Send + 'static,
704 {
705 Self::with_name(Some(name.into()), factory)
706 }
707
708 /// A branch the caller does not name. A completion predicate sees
709 /// `None`; history records `parallel-branch-{index}`.
710 ///
711 /// # Examples
712 ///
713 /// ```no_run
714 /// use aws_durable_execution_sdk::{Branch, DurableContext};
715 ///
716 /// let branch: Branch<i32> = Branch::unnamed(|_ctx: DurableContext| async move { Ok(42) });
717 /// assert_eq!(branch.name(), None);
718 /// ```
719 pub fn unnamed<F, Fut>(factory: F) -> Self
720 where
721 F: FnOnce(DurableContext) -> Fut + Send + 'static,
722 Fut: Future<Output = Result<O, BoxError>> + Send + 'static,
723 {
724 Self::with_name(None, factory)
725 }
726
727 /// Builds a branch with the caller's name, if any (internal).
728 fn with_name<F, Fut>(name: Option<String>, factory: F) -> Self
729 where
730 F: FnOnce(DurableContext) -> Fut + Send + 'static,
731 Fut: Future<Output = Result<O, BoxError>> + Send + 'static,
732 {
733 let (ctx_tx, ctx_rx) = tokio::sync::oneshot::channel::<DurableContext>();
734 Self {
735 name,
736 body: BranchBody {
737 ctx_tx,
738 // The SDK does the pinning and BoxError -> internal-carrier
739 // type erasure so callers write a plain `async move` body
740 // with `?`. This is the branch's ONE erasure: the factory
741 // closure and its concrete future both live inside this box;
742 // there is no separate closure box producing a second
743 // future box.
744 future: Box::pin(async move {
745 let ctx = ctx_rx.await.map_err(|_| {
746 ChildFnError::new("branch context was never delivered (coordinator gone)")
747 })?;
748 factory(ctx).await.map_err(ChildFnError::from)
749 }),
750 },
751 }
752 }
753
754 /// Returns the name the caller gave, or `None` for a branch built with
755 /// [`Branch::unnamed`].
756 pub fn name(&self) -> Option<&str> {
757 self.name.as_deref()
758 }
759
760 /// Consumes the branch and returns its name and erased body (internal).
761 pub(crate) fn into_parts(self) -> (Option<String>, BranchBody<O>) {
762 (self.name, self.body)
763 }
764}
765
766/// A callback token and its result future.
767///
768/// Returned by [`DurableContext::create_callback`]. Call [`id()`](Self::id)
769/// to obtain the token string that external systems use to complete the
770/// callback, and [`result()`](Self::result) to get the future that
771/// resolves when the callback arrives.
772///
773/// # Examples
774///
775/// ```no_run
776/// use aws_durable_execution_sdk as durable;
777/// use serde::{Deserialize, Serialize};
778///
779/// #[derive(Serialize, Deserialize)]
780/// struct Approval { approved: bool }
781///
782/// async fn handler(
783/// _event: serde_json::Value,
784/// ctx: durable::DurableContext,
785/// ) -> Result<bool, durable::BoxError> {
786/// let cb = ctx.create_callback::<Approval>()
787/// .name("wait-approval")
788/// .await?;
789/// let _id = cb.id(); // send to external system
790/// let approval = cb.result().await?;
791/// Ok(approval.approved)
792/// }
793/// ```
794#[derive(Debug)]
795#[non_exhaustive]
796pub struct Callback<O> {
797 id: String,
798 state: CallbackState<O>,
799}
800
801/// Resolves a pending callback from its record once the record is
802/// terminal.
803pub(crate) type CallbackResolver<O> =
804 Box<dyn FnOnce() -> Pin<Box<dyn Future<Output = Result<O, OperationError>> + Send>> + Send>;
805
806/// What a pending callback's `result()` needs, besides its context and
807/// wire ID, to build the plugin info of the callback.
808#[derive(Debug)]
809pub(crate) struct CallbackIdentity {
810 /// The callback's name.
811 pub(crate) name: Option<String>,
812 /// The name the plugin hooks report instead of `name`, if any.
813 pub(crate) plugin_name: Option<String>,
814 /// The callback's resolved subtype.
815 pub(crate) sub_type: String,
816}
817
818/// Internal state for a callback: either settled (replay) or pending (live).
819enum CallbackState<O> {
820 /// The callback has a known outcome from the checkpoint log (replay).
821 Settled(Option<Result<O, OperationError>>),
822 /// The callback is in flight: the result waits on its record.
823 Pending {
824 /// The context the callback was created on.
825 ctx: DurableContext,
826 /// The callback operation's wire ID.
827 wire_id: String,
828 /// The name, plugin name and subtype of the callback.
829 identity: CallbackIdentity,
830 /// Builds the outcome from the terminal record.
831 resolver: CallbackResolver<O>,
832 },
833}
834
835impl<O: std::fmt::Debug> std::fmt::Debug for CallbackState<O> {
836 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
837 match self {
838 Self::Settled(outcome) => f.debug_tuple("Settled").field(outcome).finish(),
839 Self::Pending {
840 ctx,
841 wire_id,
842 identity,
843 ..
844 } => f
845 .debug_struct("Pending")
846 .field("ctx", ctx)
847 .field("wire_id", wire_id)
848 .field("identity", identity)
849 .finish_non_exhaustive(),
850 }
851 }
852}
853
854impl<O: Send + 'static> Callback<O> {
855 /// Creates a settled callback (replay: outcome already known).
856 pub(crate) fn new_settled(id: String, result: Result<O, OperationError>) -> Self {
857 Self {
858 id,
859 state: CallbackState::Settled(Some(result)),
860 }
861 }
862
863 /// Creates a pending callback (live: outcome not yet known).
864 /// `resolver` builds the outcome from the record once it is terminal.
865 pub(crate) fn new_pending(
866 id: String,
867 ctx: DurableContext,
868 wire_id: String,
869 identity: CallbackIdentity,
870 resolver: CallbackResolver<O>,
871 ) -> Self {
872 Self {
873 id,
874 state: CallbackState::Pending {
875 ctx,
876 wire_id,
877 identity,
878 resolver,
879 },
880 }
881 }
882
883 /// Returns the callback ID token.
884 ///
885 /// This string is passed to an external system, which uses it to
886 /// complete the callback via the durable execution API.
887 ///
888 /// # Examples
889 ///
890 /// ```no_run
891 /// use aws_durable_execution_sdk as durable;
892 /// use serde::{Deserialize, Serialize};
893 ///
894 /// #[derive(Serialize, Deserialize)]
895 /// struct Data { value: i32 }
896 ///
897 /// async fn handler(
898 /// _event: serde_json::Value,
899 /// ctx: durable::DurableContext,
900 /// ) -> Result<(), durable::BoxError> {
901 /// let cb = ctx.create_callback::<Data>()
902 /// .await?;
903 /// println!("callback id: {}", cb.id());
904 /// let _data = cb.result().await?;
905 /// Ok(())
906 /// }
907 /// ```
908 pub fn id(&self) -> &str {
909 &self.id
910 }
911
912 /// Returns the callback result as a [`DurableFuture`].
913 ///
914 /// For settled callbacks (replay), the future resolves with the stored
915 /// outcome immediately. For pending callbacks (live), the future waits
916 /// for the external completion. It resolves in the same invocation when
917 /// a checkpoint response carries the completed callback; otherwise the
918 /// invocation suspends once no other SDK work can make progress.
919 ///
920 /// Because the return type is a [`DurableFuture`], a callback result
921 /// participates in the durable combinators
922 /// ([`try_join_all`](DurableContext::try_join_all),
923 /// [`join_all`](DurableContext::join_all),
924 /// [`select_ok`](DurableContext::select_ok),
925 /// [`race`](DurableContext::race)) exactly like any other durable
926 /// operation.
927 ///
928 /// Awaiting the future yields `Result<O, OperationError>`: an
929 /// [`OperationError`] is returned if the callback failed (timeout,
930 /// heartbeat timeout, or external failure), or if its payload could not
931 /// be decoded with a permanent failure
932 /// ([`CallbackErrorKind::DeserializationFailed`](crate::CallbackErrorKind::DeserializationFailed)),
933 /// whether the record was terminal when the callback was created or
934 /// settled while this future waited. Awaiting the result of a
935 /// pending callback on a task or thread that does not own the context
936 /// fails the execution with a context usage error.
937 ///
938 /// # Examples
939 ///
940 /// ```no_run
941 /// use aws_durable_execution_sdk as durable;
942 /// use serde::{Deserialize, Serialize};
943 ///
944 /// #[derive(Serialize, Deserialize)]
945 /// struct Payload { msg: String }
946 ///
947 /// async fn handler(
948 /// _event: serde_json::Value,
949 /// ctx: durable::DurableContext,
950 /// ) -> Result<String, durable::BoxError> {
951 /// let cb = ctx.create_callback::<Payload>()
952 /// .await?;
953 /// let payload = cb.result().await?;
954 /// Ok(payload.msg)
955 /// }
956 /// ```
957 pub fn result(self) -> DurableFuture<O> {
958 match self.state {
959 CallbackState::Settled(outcome) => DurableFuture::from_async(async move {
960 // Replay path: return the stored outcome directly.
961 outcome.unwrap_or_else(|| {
962 Err(OperationError::from_kind(
963 crate::error::OperationErrorKind::Callback(
964 crate::error::CallbackError::new(
965 crate::error::CallbackErrorKind::Internal,
966 Some("settled callback had no outcome".into()),
967 ),
968 ),
969 ))
970 })
971 }),
972 CallbackState::Pending {
973 ctx,
974 wire_id,
975 identity,
976 resolver,
977 } => Self::pending_result(ctx, wire_id, identity, resolver),
978 }
979 }
980
981 /// Waits for the callback result on its own SDK task, as `.spawn()` does
982 /// for other operations, and returns its handle. The SDK refreshes the
983 /// callback's status only after the handle is first polled. Dropping the
984 /// handle loses only the result: the wait keeps running until the
985 /// callback settles, until its scope closes, or until the invocation
986 /// ends, and dropping it does not count as the first poll. A stopped
987 /// wait stops at its next `.await`.
988 ///
989 /// For a settled callback (replay) it returns the same future as
990 /// [`result()`](Self::result), which resolves with the stored outcome
991 /// and starts no task. In both its settled and pending forms it returns
992 /// the same callback outcomes and errors as `result()`, a permanent
993 /// payload decode failure included.
994 ///
995 /// # Errors
996 ///
997 /// For a pending callback, the task runs on the invocation's runtime;
998 /// when the invocation coordinator was created without one, the returned
999 /// future resolves to an error. A settled callback needs no
1000 /// runtime. For a pending callback, a call on a task or thread that
1001 /// does not own the context fails the execution with a context usage
1002 /// error.
1003 ///
1004 /// # Examples
1005 ///
1006 /// ```no_run
1007 /// use aws_durable_execution_sdk as durable;
1008 ///
1009 /// async fn handler(
1010 /// _event: serde_json::Value,
1011 /// ctx: durable::DurableContext,
1012 /// ) -> Result<String, durable::BoxError> {
1013 /// let cb = ctx.create_callback::<String>().name("approval").await?;
1014 /// let approval = cb.spawn_result();
1015 /// ctx.step(|_| async { Ok(()) }).name("other-work").await?;
1016 /// Ok(approval.await?)
1017 /// }
1018 /// ```
1019 pub fn spawn_result(self) -> DurableFuture<O> {
1020 match self.state {
1021 CallbackState::Settled(_) => self.result(),
1022 CallbackState::Pending {
1023 ctx,
1024 wire_id,
1025 identity,
1026 resolver,
1027 } => {
1028 let flag = Arc::new(AtomicBool::new(false));
1029 let waiting = ctx.with_awaited(Arc::clone(&flag));
1030 // `pending_result` builds the future through `for_operation`,
1031 // so the task gets the creating context's frames and the span
1032 // current here. The capture point is this call, as for
1033 // `.spawn()`: it is where the user starts the waiting task.
1034 let future = Self::pending_result(waiting, wire_id, identity, resolver);
1035 DurableFuture::spawn_blessed(future, &ctx, Some(flag))
1036 }
1037 }
1038 }
1039
1040 /// The future of a pending callback's result. It waits until the record
1041 /// is terminal, then builds the outcome from it as creation-time replay
1042 /// does.
1043 ///
1044 /// The record becomes terminal while this future waits in the
1045 /// invocation. A `SUCCEEDED`, `FAILED`, `TIMED_OUT`, `STOPPED` or
1046 /// `CANCELLED` record therefore fires `on_operation_end` with
1047 /// `is_replay` false before the outcome is built.
1048 fn pending_result(
1049 ctx: DurableContext,
1050 wire_id: String,
1051 identity: CallbackIdentity,
1052 resolver: CallbackResolver<O>,
1053 ) -> DurableFuture<O> {
1054 let gate = ctx.clone();
1055 DurableFuture::for_operation(&gate, async move {
1056 // Execution entry: a task or thread that does not own the
1057 // context fails the execution. A settled result executes
1058 // nothing, so it is not checked.
1059 ctx.enforce_task_ownership()?;
1060 ctx.wait_for_record(&wire_id, |status| {
1061 !matches!(
1062 status,
1063 crate::engine::CheckpointStatus::Started
1064 | crate::engine::CheckpointStatus::Pending
1065 )
1066 })
1067 .await;
1068 if let Some(plugins) = ctx.plugins() {
1069 let terminal = ctx
1070 .with_checkpoint_record_by_wire(&wire_id, |record| {
1071 crate::callback::is_terminal_callback_status(&record.status)
1072 })
1073 .unwrap_or(false);
1074 if terminal {
1075 let info = crate::callback::callback_info(
1076 &ctx,
1077 &wire_id,
1078 &identity.sub_type,
1079 identity.name.as_deref(),
1080 identity.plugin_name.as_deref(),
1081 )
1082 .with_replay(false);
1083 crate::plugin::operation_ended(plugins, &info);
1084 }
1085 }
1086 resolver().await
1087 })
1088 }
1089}
1090
1091/// A set of parallel branches whose results have different types, for
1092/// [`DurableContext::parallel_mixed`].
1093///
1094/// Each [`add`](Self::add) or [`add_with_serdes`](Self::add_with_serdes)
1095/// call adds one branch and returns a [`BranchHandle`] typed with that
1096/// branch's result. Branches start, and are numbered, in the order they
1097/// were added. The number of branches is unlimited.
1098///
1099/// # Examples
1100///
1101/// ```no_run
1102/// use aws_durable_execution_sdk as durable;
1103/// use durable::BranchSet;
1104///
1105/// async fn handler(
1106/// _event: serde_json::Value,
1107/// ctx: durable::DurableContext,
1108/// ) -> Result<String, durable::BoxError> {
1109/// let mut branches = BranchSet::new();
1110/// let count = branches.add("count", |_ctx| async { Ok(7_u32) });
1111/// let label = branches.add("label", |_ctx| async { Ok("ready".to_owned()) });
1112/// ctx.parallel_mixed(branches).name("fan-out").await?;
1113/// Ok(format!("{}: {}", count.into_result()?, label.into_result()?))
1114/// }
1115/// ```
1116#[non_exhaustive]
1117pub struct BranchSet {
1118 /// Each branch's caller name and erased body, in the order added.
1119 branches: Vec<(Option<String>, BranchBody<BranchValue>)>,
1120 /// Each branch's decoder, at the branch's index.
1121 decoders: Vec<Arc<dyn BranchDecoder>>,
1122 /// Whether each branch uses the default JSON serdes, at its index.
1123 json: Vec<bool>,
1124 /// The set's identity, shared by every key and value of its branches.
1125 identity: Arc<SetIdentity>,
1126}
1127
1128/// The identity of one [`BranchSet`]: each set allocates its own, and two
1129/// identities are the same exactly when they are the same allocation.
1130struct SetIdentity;
1131
1132impl Default for BranchSet {
1133 fn default() -> Self {
1134 Self::new()
1135 }
1136}
1137
1138impl std::fmt::Debug for BranchSet {
1139 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1140 let names: Vec<&str> = self
1141 .branches
1142 .iter()
1143 .map(|(name, _)| name.as_deref().unwrap_or_default())
1144 .collect();
1145 f.debug_struct("BranchSet")
1146 .field("names", &names)
1147 .finish_non_exhaustive()
1148 }
1149}
1150
1151impl BranchSet {
1152 /// Creates an empty set.
1153 #[must_use]
1154 pub fn new() -> Self {
1155 Self {
1156 branches: Vec::new(),
1157 decoders: Vec::new(),
1158 json: Vec::new(),
1159 identity: Arc::new(SetIdentity),
1160 }
1161 }
1162
1163 /// Adds a branch whose result is encoded and decoded as JSON.
1164 ///
1165 /// This is [`add_with_serdes`](Self::add_with_serdes) with
1166 /// [`JsonSerdes`](crate::JsonSerdes). The batch record holds the
1167 /// branch's value as JSON, as [`DurableContext::parallel`] does with
1168 /// its default serdes.
1169 #[must_use]
1170 pub fn add<T, F, Fut>(&mut self, name: impl Into<String>, factory: F) -> BranchHandle<T>
1171 where
1172 T: serde::Serialize + serde::de::DeserializeOwned + Send + 'static,
1173 F: FnOnce(DurableContext) -> Fut + Send + 'static,
1174 Fut: Future<Output = Result<T, BoxError>> + Send + 'static,
1175 {
1176 self.insert(name.into(), crate::JsonSerdes, factory, true)
1177 }
1178
1179 /// Adds a branch whose result is encoded and decoded by `serdes`.
1180 ///
1181 /// `name` and `factory` have the same types as in [`Branch::new`].
1182 /// History records `name`, or `parallel-branch-{index}` when it is
1183 /// empty, and a completion predicate sees `Some(name)`. `serdes` must
1184 /// implement [`Serdes<T>`](crate::Serdes), so a serdes written for
1185 /// another type fails to compile. It is called wherever the item serdes
1186 /// of [`DurableContext::parallel`] is called for this branch, with the
1187 /// same [`SerdesContext`](crate::serdes::SerdesContext). To share one
1188 /// serdes across branches, pass a clone of one `Arc` to each call.
1189 ///
1190 /// # Examples
1191 ///
1192 /// ```no_run
1193 /// use std::sync::Arc;
1194 ///
1195 /// use aws_durable_execution_sdk as durable;
1196 /// use durable::serdes::{FileSystemSerdes, SerdesContext};
1197 /// use durable::{BoxError, BranchSet, Serdes};
1198 ///
1199 /// struct Order {
1200 /// id: u64,
1201 /// }
1202 ///
1203 /// // A serdes for `Order` only: attaching it to a branch of another
1204 /// // type fails to compile.
1205 /// struct OrderSerdes;
1206 ///
1207 /// impl Serdes<Order> for OrderSerdes {
1208 /// async fn serialize(&self, value: Order, _ctx: SerdesContext) -> Result<String, BoxError> {
1209 /// Ok(value.id.to_string())
1210 /// }
1211 /// async fn deserialize(&self, wire: String, _ctx: SerdesContext) -> Result<Order, BoxError> {
1212 /// Ok(Order { id: wire.parse()? })
1213 /// }
1214 /// }
1215 ///
1216 /// async fn handler(
1217 /// _event: serde_json::Value,
1218 /// ctx: durable::DurableContext,
1219 /// ) -> Result<u64, durable::BoxError> {
1220 /// let files = Arc::new(FileSystemSerdes::new("/mnt/efs"));
1221 /// let mut branches = BranchSet::new();
1222 /// let order = branches.add_with_serdes("order", OrderSerdes, |_ctx| async {
1223 /// Ok(Order { id: 42 })
1224 /// });
1225 /// let report = branches.add_with_serdes("report", Arc::clone(&files), |_ctx| async {
1226 /// Ok("a large report".to_owned())
1227 /// });
1228 /// ctx.parallel_mixed(branches).name("process-order").await?;
1229 /// let order = order.into_result()?;
1230 /// let _report: String = report.into_result()?;
1231 /// Ok(order.id)
1232 /// }
1233 /// ```
1234 #[must_use]
1235 pub fn add_with_serdes<T, S, F, Fut>(
1236 &mut self,
1237 name: impl Into<String>,
1238 serdes: S,
1239 factory: F,
1240 ) -> BranchHandle<T>
1241 where
1242 T: Send + 'static,
1243 S: crate::Serdes<T> + 'static,
1244 F: FnOnce(DurableContext) -> Fut + Send + 'static,
1245 Fut: Future<Output = Result<T, BoxError>> + Send + 'static,
1246 {
1247 self.insert(name.into(), serdes, factory, false)
1248 }
1249
1250 /// Adds one branch (internal). `json` is `true` when the batch record
1251 /// holds the branch's value as JSON.
1252 fn insert<T, S, F, Fut>(
1253 &mut self,
1254 name: String,
1255 serdes: S,
1256 factory: F,
1257 json: bool,
1258 ) -> BranchHandle<T>
1259 where
1260 T: Send + 'static,
1261 S: crate::Serdes<T> + 'static,
1262 F: FnOnce(DurableContext) -> Fut + Send + 'static,
1263 Fut: Future<Output = Result<T, BoxError>> + Send + 'static,
1264 {
1265 let index = self.branches.len();
1266 let record_name = if name.is_empty() {
1267 format!("parallel-branch-{index}")
1268 } else {
1269 name.clone()
1270 };
1271 let key = BranchKey {
1272 identity: Arc::clone(&self.identity),
1273 index,
1274 _marker: PhantomData,
1275 };
1276 let slot: BranchSlot<T> = Arc::new(std::sync::Mutex::new(None));
1277 let serdes = Arc::new(serdes);
1278 let decoder = BranchShared {
1279 serdes: Arc::clone(&serdes),
1280 slot: Arc::clone(&slot),
1281 identity: Arc::clone(&self.identity),
1282 index,
1283 };
1284 let body_slot = Arc::clone(&slot);
1285 let body_identity = Arc::clone(&self.identity);
1286 let branch = Branch::new(name, move |ctx: DurableContext| async move {
1287 let value = factory(ctx).await?;
1288 Ok(BranchValue {
1289 value: Box::new(TypedBranchValue {
1290 value,
1291 serdes,
1292 slot: body_slot,
1293 }),
1294 identity: body_identity,
1295 index,
1296 })
1297 });
1298 self.branches.push(branch.into_parts());
1299 self.decoders.push(Arc::new(decoder));
1300 self.json.push(json);
1301 BranchHandle {
1302 name: record_name,
1303 slot,
1304 key,
1305 }
1306 }
1307
1308 /// Consumes the set and returns each branch's caller name and body,
1309 /// the decoders and the JSON flags, all in branch order (internal).
1310 #[expect(clippy::type_complexity)]
1311 // reason: the three parts go to three different places, and a named type for each would add nothing
1312 pub(crate) fn into_parts(
1313 self,
1314 ) -> (
1315 Vec<(Option<String>, BranchBody<BranchValue>)>,
1316 Arc<Vec<Arc<dyn BranchDecoder>>>,
1317 Arc<[bool]>,
1318 ) {
1319 (self.branches, Arc::new(self.decoders), Arc::from(self.json))
1320 }
1321}
1322
1323/// The result of one branch of a [`BranchSet`].
1324///
1325/// [`into_result`](Self::into_result) returns the branch's result once the
1326/// `.await` of the [`DurableContext::parallel_mixed`] that ran the set has
1327/// returned, or the `.await` of the future its `.spawn()` returned. Before
1328/// that, the handle has no result, even when its branch
1329/// has finished, so what a handle returns never depends on timing. Dropping
1330/// a handle does not cancel or skip its branch.
1331#[non_exhaustive]
1332pub struct BranchHandle<T> {
1333 /// The name history records for the branch.
1334 name: String,
1335 /// Shared with the branch: filled when the parallel's `.await` returns.
1336 slot: BranchSlot<T>,
1337 /// The branch's key.
1338 key: BranchKey<T>,
1339}
1340
1341impl<T> std::fmt::Debug for BranchHandle<T> {
1342 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1343 let has_result = lock_slot(&self.slot).is_some();
1344 f.debug_struct("BranchHandle")
1345 .field("name", &self.name)
1346 .field("has_result", &has_result)
1347 .finish_non_exhaustive()
1348 }
1349}
1350
1351impl<T> BranchHandle<T> {
1352 /// Returns the key that reads this branch's value from the
1353 /// [`BatchResult`](crate::builders::map_parallel::BatchResult) a
1354 /// [`ParallelMixedBuilder::summary`](crate::builders::ParallelMixedBuilder::summary)
1355 /// receives, with
1356 /// [`BatchResult::value`](crate::builders::map_parallel::BatchResult::value).
1357 ///
1358 /// Every call returns a key of the same branch.
1359 #[must_use]
1360 pub fn key(&self) -> BranchKey<T> {
1361 self.key.clone()
1362 }
1363
1364 /// Returns the branch's result, without waiting.
1365 ///
1366 /// - `Ok(value)` when the branch succeeded. `value` is what the
1367 /// branch's serdes decoded, so the first run and replay return the
1368 /// same value.
1369 /// - The branch's own error when the branch failed: a
1370 /// [`ChildContextError`](crate::ChildContextError) of kind
1371 /// [`ChildFailed`](crate::ChildContextErrorKind::ChildFailed) that
1372 /// holds the recorded failure, the error `parallel(...).await`
1373 /// returns when a failed item ends the batch.
1374 ///
1375 /// # Errors
1376 ///
1377 /// Besides the branch's own error, returns an error of kind
1378 /// [`NotCompleted`](crate::ChildContextErrorKind::NotCompleted), whose
1379 /// message names the branch, when the handle has no result: the
1380 /// parallel has not returned, it returned an error of its own, the
1381 /// branch never started, or the batch completed while the branch still
1382 /// ran.
1383 pub fn into_result(self) -> Result<T, OperationError> {
1384 let taken = lock_slot(&self.slot).take();
1385 taken.unwrap_or_else(|| Err(not_completed_error(&self.name)))
1386 }
1387}
1388
1389/// The slot a [`BranchHandle`] shares with its branch.
1390type BranchSlot<T> = Arc<std::sync::Mutex<Option<Result<T, OperationError>>>>;
1391
1392/// Locks a branch slot. A poisoned lock still holds a valid slot value.
1393fn lock_slot<T>(
1394 slot: &std::sync::Mutex<Option<Result<T, OperationError>>>,
1395) -> std::sync::MutexGuard<'_, Option<Result<T, OperationError>>> {
1396 slot.lock()
1397 .unwrap_or_else(std::sync::PoisonError::into_inner)
1398}
1399
1400/// The error of a [`BranchHandle`] that has no result.
1401fn not_completed_error(name: &str) -> OperationError {
1402 OperationError::from_kind(crate::OperationErrorKind::ChildContext(
1403 crate::error::ChildContextError::new(
1404 crate::ChildContextErrorKind::NotCompleted,
1405 Some(format!("parallel branch \"{name}\" has no result").into()),
1406 ),
1407 ))
1408}
1409
1410/// The value of one branch of a [`BranchSet`], with its type erased: the
1411/// item type of the [`BatchResult`](crate::builders::map_parallel::BatchResult) that a
1412/// [`ParallelMixedBuilder::summary`](crate::builders::ParallelMixedBuilder::summary)
1413/// receives.
1414///
1415/// A `BranchValue` exposes nothing of its value. Read the value with
1416/// [`BatchResult::value`](crate::builders::map_parallel::BatchResult::value) and the key that
1417/// [`BranchHandle::key`] returns. Its `Debug` text is `BranchValue { .. }`.
1418pub struct BranchValue {
1419 /// The value, with its serdes and its handle's slot.
1420 value: Box<dyn ErasedBranchValue>,
1421 /// The identity of the set the branch belongs to.
1422 identity: Arc<SetIdentity>,
1423 /// The branch's index in its set.
1424 index: usize,
1425}
1426
1427impl std::fmt::Debug for BranchValue {
1428 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1429 f.debug_struct("BranchValue").finish_non_exhaustive()
1430 }
1431}
1432
1433impl BranchValue {
1434 /// Encodes the value with its branch's serdes (internal).
1435 pub(crate) fn encode(
1436 self,
1437 ctx: crate::serdes::SerdesContext,
1438 ) -> Pin<Box<dyn Future<Output = Result<String, BoxError>> + Send>> {
1439 self.value.encode(ctx)
1440 }
1441
1442 /// Stores `Ok(value)` in the branch handle's slot (internal).
1443 pub(crate) fn publish(self) {
1444 self.value.publish();
1445 }
1446
1447 /// Returns the value when it belongs to `key`'s branch (internal).
1448 pub(crate) fn of_branch<T: 'static>(&self, key: &BranchKey<T>) -> Option<&T> {
1449 if !Arc::ptr_eq(&self.identity, &key.identity) || self.index != key.index {
1450 return None;
1451 }
1452 #[expect(clippy::expect_used)]
1453 // reason: the set and the index name one branch, and that branch's
1454 // body and decoder produce only values of the type of its key
1455 let value = self
1456 .value
1457 .value()
1458 .downcast_ref::<T>()
1459 .expect("a branch's key has the type of the branch's values");
1460 Some(value)
1461 }
1462}
1463
1464/// The key of one branch of a [`BranchSet`], which reads the branch's value
1465/// from a [`BatchResult<BranchValue>`](crate::builders::map_parallel::BatchResult) with
1466/// [`BatchResult::value`](crate::builders::map_parallel::BatchResult::value).
1467///
1468/// [`BranchHandle::key`] returns it. A key reads only values of its own
1469/// branch: a key from another set returns `None`. It is `Clone`, `Send`
1470/// and `Sync` for every branch type, and holds no value of type `T`.
1471///
1472/// A key's type is exactly its branch's type. Subtyping cannot turn a key
1473/// of one type into a key of another, so a key never reads a value as a
1474/// type the branch did not produce:
1475///
1476/// ```compile_fail,E0308
1477/// use aws_durable_execution_sdk::BranchKey;
1478///
1479/// fn coerce(key: BranchKey<for<'a> fn(&'a ())>) -> BranchKey<fn(&'static ())> {
1480/// key
1481/// }
1482/// ```
1483pub struct BranchKey<T> {
1484 /// The identity of the set the branch belongs to.
1485 identity: Arc<SetIdentity>,
1486 /// The branch's index in its set.
1487 index: usize,
1488 /// The branch's type, without owning a `T`. `fn(T) -> T` makes the key
1489 /// invariant in `T`, so subtyping cannot change the type it reads.
1490 _marker: PhantomData<fn(T) -> T>,
1491}
1492
1493impl<T> BranchKey<T> {
1494 /// The branch's index in its set (internal).
1495 pub(crate) fn index(&self) -> usize {
1496 self.index
1497 }
1498}
1499
1500impl<T> Clone for BranchKey<T> {
1501 fn clone(&self) -> Self {
1502 Self {
1503 identity: Arc::clone(&self.identity),
1504 index: self.index,
1505 _marker: PhantomData,
1506 }
1507 }
1508}
1509
1510impl<T> std::fmt::Debug for BranchKey<T> {
1511 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1512 f.debug_struct("BranchKey")
1513 .field("index", &self.index)
1514 .finish_non_exhaustive()
1515 }
1516}
1517
1518/// A branch value whose type is erased (crate-internal).
1519pub(crate) trait ErasedBranchValue: Send {
1520 /// Encodes the value with the branch's serdes.
1521 fn encode(
1522 self: Box<Self>,
1523 ctx: crate::serdes::SerdesContext,
1524 ) -> Pin<Box<dyn Future<Output = Result<String, BoxError>> + Send>>;
1525 /// Stores `Ok(value)` in the branch handle's slot.
1526 fn publish(self: Box<Self>);
1527 /// Returns the value.
1528 fn value(&self) -> &dyn std::any::Any;
1529}
1530
1531/// Decodes the values of one branch and fails its handle (crate-internal).
1532pub(crate) trait BranchDecoder: Send + Sync {
1533 /// Decodes a wire string with the branch's serdes.
1534 fn decode(
1535 &self,
1536 wire: String,
1537 ctx: crate::serdes::SerdesContext,
1538 ) -> Pin<Box<dyn Future<Output = Result<BranchValue, BoxError>> + Send + '_>>;
1539 /// Stores `Err(err)` in the branch handle's slot.
1540 fn publish_error(&self, err: OperationError);
1541}
1542
1543/// A branch's value with its serdes and its handle's slot.
1544struct TypedBranchValue<T, S> {
1545 value: T,
1546 serdes: Arc<S>,
1547 slot: BranchSlot<T>,
1548}
1549
1550impl<T, S> ErasedBranchValue for TypedBranchValue<T, S>
1551where
1552 T: Send + 'static,
1553 S: crate::Serdes<T>,
1554{
1555 fn encode(
1556 self: Box<Self>,
1557 ctx: crate::serdes::SerdesContext,
1558 ) -> Pin<Box<dyn Future<Output = Result<String, BoxError>> + Send>> {
1559 let Self { value, serdes, .. } = *self;
1560 Box::pin(async move { serdes.serialize(value, ctx).await })
1561 }
1562
1563 fn publish(self: Box<Self>) {
1564 let Self { value, slot, .. } = *self;
1565 *lock_slot(&slot) = Some(Ok(value));
1566 }
1567
1568 fn value(&self) -> &dyn std::any::Any {
1569 &self.value
1570 }
1571}
1572
1573/// One branch's serdes, handle slot, set identity and index: the branch's
1574/// [`BranchDecoder`].
1575struct BranchShared<T, S> {
1576 serdes: Arc<S>,
1577 slot: BranchSlot<T>,
1578 identity: Arc<SetIdentity>,
1579 index: usize,
1580}
1581
1582impl<T, S> BranchDecoder for BranchShared<T, S>
1583where
1584 T: Send + 'static,
1585 S: crate::Serdes<T>,
1586{
1587 fn decode(
1588 &self,
1589 wire: String,
1590 ctx: crate::serdes::SerdesContext,
1591 ) -> Pin<Box<dyn Future<Output = Result<BranchValue, BoxError>> + Send + '_>> {
1592 Box::pin(async move {
1593 let value = self.serdes.deserialize(wire, ctx).await?;
1594 Ok(BranchValue {
1595 value: Box::new(TypedBranchValue {
1596 value,
1597 serdes: Arc::clone(&self.serdes),
1598 slot: Arc::clone(&self.slot),
1599 }),
1600 identity: Arc::clone(&self.identity),
1601 index: self.index,
1602 })
1603 })
1604 }
1605
1606 fn publish_error(&self, err: OperationError) {
1607 *lock_slot(&self.slot) = Some(Err(err));
1608 }
1609}
1610
1611#[cfg(test)]
1612#[expect(clippy::panic)]
1613// reason: test assertions
1614// Tests deliberately spawn foreign (unblessed) tasks to exercise runtime
1615// behavior; production spawning is confined to the src/task.rs gateway.
1616#[expect(clippy::disallowed_methods)]
1617mod tests {
1618 use super::*;
1619 use crate::engine::CheckpointLog;
1620 use std::sync::Arc;
1621 use std::sync::atomic::{AtomicBool, Ordering};
1622
1623 fn test_ctx_with_client() -> DurableContext {
1624 let client = Arc::new(crate::client::InMemoryExecutionClient::new(Vec::new()));
1625 DurableContext::new_root_with_client(
1626 "test-function-arn".to_owned(),
1627 lambda_runtime::Context::default(),
1628 Arc::new(CheckpointLog::empty()),
1629 client,
1630 "token0".to_owned(),
1631 )
1632 }
1633
1634 use std::future::IntoFuture as _;
1635
1636 thread_local! {
1637 /// The wraps of [`Tag`] plugins entered on this thread, outermost
1638 /// first.
1639 static TAGS: std::cell::RefCell<Vec<String>> = const { std::cell::RefCell::new(Vec::new()) };
1640 /// Each user-function wrap entered on this thread: its tag and the
1641 /// tags entered around it.
1642 static ENTERED: std::cell::RefCell<Vec<(String, Vec<String>)>> = const { std::cell::RefCell::new(Vec::new()) };
1643 }
1644
1645 fn current_tags() -> Vec<String> {
1646 TAGS.with(|tags| tags.borrow().clone())
1647 }
1648
1649 /// A plugin whose wraps record `inv`, or the user function's name (its
1650 /// ID without one), while they are entered.
1651 struct Tag;
1652
1653 impl Tag {
1654 fn wrap(site: &str, next: &mut dyn FnMut()) {
1655 TAGS.with(|tags| tags.borrow_mut().push(site.to_owned()));
1656 next();
1657 TAGS.with(|tags| tags.borrow_mut().pop());
1658 }
1659 }
1660
1661 impl crate::plugin::Plugin for Tag {
1662 fn wrap_invocation(&self, _info: &crate::plugin::InvocationInfo, next: &mut dyn FnMut()) {
1663 Self::wrap("inv", next);
1664 }
1665
1666 fn wrap_user_function(&self, info: &crate::plugin::OperationInfo, next: &mut dyn FnMut()) {
1667 let site = info.name().unwrap_or(info.id());
1668 ENTERED.with(|entered| {
1669 entered.borrow_mut().push((site.to_owned(), current_tags()));
1670 });
1671 Self::wrap(site, next);
1672 }
1673 }
1674
1675 impl crate::plugin::PluginFactory for Tag {
1676 fn create_plugin(
1677 &self,
1678 _info: &crate::plugin::InvocationInfo,
1679 ) -> Result<Option<Box<dyn crate::plugin::Plugin>>, BoxError> {
1680 Ok(Some(Box::new(Tag)))
1681 }
1682 }
1683
1684 /// A root context over the in-memory transport whose one plugin is a
1685 /// [`Tag`], and its invocation frames.
1686 fn tagged_ctx() -> (DurableContext, crate::plugin::Frames) {
1687 let factory: Arc<dyn crate::plugin::PluginFactory> = Arc::new(Tag);
1688 let plugins = crate::plugin::create_plugins(
1689 &[("Tag", factory)],
1690 None,
1691 crate::plugin::tests_support_info,
1692 )
1693 .expect("a factory was given");
1694 let ctx = DurableContext::new_root_with_client_and_defaults(
1695 "test-function-arn".to_owned(),
1696 lambda_runtime::Context::default(),
1697 Arc::new(CheckpointLog::empty()),
1698 Arc::new(crate::client::InMemoryExecutionClient::new(Vec::new())),
1699 "token0".to_owned(),
1700 std::time::Duration::ZERO,
1701 0,
1702 Some(Arc::clone(&plugins)),
1703 );
1704 (ctx, crate::plugin::Frames::invocation(Some(plugins)))
1705 }
1706
1707 /// What a step body saw: its name and the wraps entered at its call.
1708 type Seen = Arc<std::sync::Mutex<Vec<(&'static str, Vec<String>)>>>;
1709
1710 /// A step body that records what it saw in `seen`, then returns
1711 /// `value`.
1712 fn recording(
1713 seen: &Seen,
1714 name: &'static str,
1715 value: u32,
1716 ) -> impl FnOnce(crate::StepContext) -> std::future::Ready<Result<u32, BoxError>>
1717 + Clone
1718 + Send
1719 + 'static {
1720 let seen = Arc::clone(seen);
1721 move |_| {
1722 seen.lock().unwrap().push((name, current_tags()));
1723 std::future::ready(Ok(value))
1724 }
1725 }
1726
1727 /// Rule 5.4: in A (child `a`, span `A`) a step future is made and
1728 /// mapped, and so is an unclaimed `try_join_all` of two steps. The
1729 /// mapped step keeps A. Mapping claims no ID; the combinator claims the
1730 /// next positional ID in B (child `b`, span `B`), by its first poll, then
1731 /// by what `.spawn()` does; and its task context is B's. Each path
1732 /// yields its inputs' mapped result; the join runs in `[I, b, join]`,
1733 /// and each input's body in the frames it captured in A.
1734 #[test]
1735 fn map_output_keeps_task_context_and_pending_claim() {
1736 let subscriber = lambda_runtime::tracing::subscriber::registry();
1737 {
1738 let _guard = test_tracing::install_test_subscriber(subscriber);
1739 let runtime = tokio::runtime::Builder::new_current_thread()
1740 .build()
1741 .expect("runtime");
1742 let _guard = runtime.enter();
1743 let span_a = tracing::info_span!("A");
1744 let span_b = tracing::info_span!("B");
1745 assert!(span_a.id().is_some() && span_b.id().is_some());
1746 for spawned in [false, true] {
1747 let (ctx, inv) = tagged_ctx();
1748 let frames_a =
1749 inv.with_user_function(Arc::new(crate::plugin::OperationInfo::for_test("a")));
1750 let frames_b =
1751 inv.with_user_function(Arc::new(crate::plugin::OperationInfo::for_test("b")));
1752 let seen: Seen = Arc::default();
1753 let (step, mut join) = span_a.in_scope(|| {
1754 frames_a.enter(|| {
1755 let step = ctx
1756 .step(recording(&seen, "solo", 1))
1757 .name("solo")
1758 .future()
1759 .map_output(|r| r.map(|v| v + 1));
1760 let s1 = ctx.step(recording(&seen, "s1", 1)).name("s1").future();
1761 let s2 = ctx.step(recording(&seen, "s2", 2)).name("s2").future();
1762 let join = ctx
1763 .try_join_all([s1, s2])
1764 .name("join")
1765 .into_future()
1766 .map_output(|r| r.map(|v| v.iter().sum::<u32>() * 10));
1767 (step, join)
1768 })
1769 });
1770 // The mapped step keeps A.
1771 assert_eq!(
1772 step.task_context().frames().enter(current_tags),
1773 ["inv", "a"],
1774 "spawned: {spawned}"
1775 );
1776 assert_eq!(step.task_context().span().id(), span_a.id());
1777 // The claim is kept, and mapping claimed nothing: the steps
1778 // took 1 to 3, so the probe takes 4.
1779 assert!(join.is_unclaimed_combinator(), "spawned: {spawned}");
1780 assert_eq!(ctx.mint_id().positional(), "4", "spawned: {spawned}");
1781 span_b.in_scope(|| {
1782 frames_b.enter(|| {
1783 if spawned {
1784 // What `.spawn()` does: claim, then start the task.
1785 join.claim_now();
1786 } else {
1787 // The first poll claims.
1788 let waker = std::task::Waker::noop();
1789 let mut cx = Context::from_waker(waker);
1790 drop(Pin::new(&mut join).poll(&mut cx));
1791 }
1792 });
1793 });
1794 assert!(!join.is_unclaimed_combinator(), "spawned: {spawned}");
1795 // The combinator claimed 5, the ID after the probe's 4.
1796 assert_eq!(ctx.mint_id().positional(), "6", "spawned: {spawned}");
1797 assert_eq!(
1798 join.task_context().frames().enter(current_tags),
1799 ["inv", "b"],
1800 "the claim captured B's frames; spawned: {spawned}"
1801 );
1802 assert_eq!(join.task_context().span().id(), span_b.id());
1803 let step = DurableFuture::spawn_blessed(step, &ctx, None);
1804 assert_eq!(runtime.block_on(step).expect("the step succeeds"), 2);
1805 let join = DurableFuture::spawn_blessed(join, &ctx, None);
1806 assert_eq!(runtime.block_on(join).expect("the join succeeds"), 30);
1807 let mut seen = std::mem::take(&mut *seen.lock().unwrap());
1808 seen.sort_by_key(|(name, _)| *name);
1809 let tags = |list: &[&str]| -> Vec<String> {
1810 list.iter().map(|tag| (*tag).to_owned()).collect()
1811 };
1812 // Each input's body runs on its own task, in the frames it
1813 // captured in A.
1814 assert_eq!(
1815 seen,
1816 [
1817 ("s1", tags(&["inv", "a", "s1"])),
1818 ("s2", tags(&["inv", "a", "s2"])),
1819 ("solo", tags(&["inv", "a", "solo"])),
1820 ],
1821 "spawned: {spawned}"
1822 );
1823 // The join's node sits above B: its wrap is entered inside
1824 // B's frames, so the join runs in `[I, b, join]`.
1825 let entered = ENTERED.with(|entered| std::mem::take(&mut *entered.borrow_mut()));
1826 let joins: Vec<_> = entered.iter().filter(|(site, _)| site == "join").collect();
1827 assert!(!joins.is_empty(), "the join ran as a user function");
1828 assert!(
1829 joins
1830 .iter()
1831 .all(|(_, around)| *around == tags(&["inv", "b"])),
1832 "{entered:?}; spawned: {spawned}"
1833 );
1834 }
1835 };
1836 }
1837
1838 /// r7 item 5: a `parallel_mixed` future keeps the task context of its
1839 /// batch, so a task that runs it runs inside the span and frames of its
1840 /// creation.
1841 #[test]
1842 fn parallel_mixed_keeps_the_task_context_of_its_creation() {
1843 let subscriber = lambda_runtime::tracing::subscriber::registry();
1844 {
1845 let _guard = test_tracing::install_test_subscriber(subscriber);
1846 let runtime = tokio::runtime::Builder::new_current_thread()
1847 .build()
1848 .expect("runtime");
1849 let _guard = runtime.enter();
1850 let ctx = test_ctx_with_client();
1851 let span = tracing::info_span!("creation");
1852 let mixed = span.in_scope(|| {
1853 let mut set = BranchSet::new();
1854 let _handle = set.add("b", |_c| async { Ok(1_u32) });
1855 ctx.parallel_mixed(set).into_future()
1856 });
1857 assert!(span.id().is_some());
1858 assert_eq!(mixed.task_context().span().id(), span.id());
1859 let plain = span.in_scope(|| ctx.step(|_| async { Ok(1_u32) }).future());
1860 let mapped = plain.map_output(|r| r.map(|v| v + 1));
1861 assert_eq!(mapped.task_context().span().id(), span.id());
1862 };
1863 }
1864
1865 /// Tokio may give a new task the ID of a task that exited, and the
1866 /// exited task's blessing is gone. So a raw task whose ID matches a
1867 /// poller that passed earlier must still be refused: the gate checks
1868 /// ownership on every poll. The test gives one task the identity the
1869 /// gate admitted: it blesses the task, passes the gate, then removes
1870 /// the blessing, as the task gateway does when a blessed task exits,
1871 /// and polls the same gate again with that task ID. A gate that cached
1872 /// the ID of its last passing poller would admit the second poll.
1873 #[test]
1874 fn poll_gate_refuses_raw_task_with_reused_identity() {
1875 let ctx = test_ctx_with_client();
1876 let mut gate = PollGate::new(&ctx);
1877 let ownership = Arc::clone(ctx.task_ownership());
1878 let runtime = tokio::runtime::Builder::new_current_thread()
1879 .build()
1880 .unwrap();
1881 let (first, second) = runtime
1882 .block_on(async move {
1883 tokio::spawn(async move {
1884 let id = tokio::task::id();
1885 ownership.bless_task(id);
1886 let first = gate.admit().is_ok();
1887 ownership.unbless_task(id);
1888 let second = gate.admit().is_ok();
1889 (first, second)
1890 })
1891 .await
1892 })
1893 .unwrap();
1894 assert!(first, "the blessed task was refused");
1895 assert!(!second, "a raw task with a reused task ID was admitted");
1896 let fatal = ctx.coordinator().fatal_error().expect("fatal recorded");
1897 assert_eq!(
1898 fatal.error_message,
1899 crate::context::foreign_caller_message("execute")
1900 );
1901 }
1902
1903 /// Test 16: a combinator future claims one ID however often
1904 /// `claim_now` runs, and its first poll after a claim claims nothing.
1905 #[tokio::test]
1906 async fn claim_now_claims_once() {
1907 let ctx = test_ctx_with_client();
1908 let mut all = ctx.try_join_all(Vec::<DurableFuture<i32>>::new()).future();
1909 assert!(all.is_unclaimed_combinator());
1910 all.claim_now();
1911 assert!(!all.is_unclaimed_combinator());
1912 all.claim_now();
1913 assert_eq!(
1914 all.await.expect("an empty join succeeds"),
1915 Vec::<i32>::new()
1916 );
1917 assert_eq!(
1918 ctx.mint_id().positional(),
1919 "2",
1920 "the combinator claimed 1 only"
1921 );
1922 }
1923
1924 /// Test 17: a step's future carries no pending claim.
1925 #[tokio::test]
1926 async fn claim_now_is_noop_for_non_combinator() {
1927 let ctx = test_ctx_with_client();
1928 let mut step = ctx.step(|_| async { Ok(1_i32) }).future();
1929 assert!(!step.is_unclaimed_combinator());
1930 assert_eq!(step.unclaimed_input_message("9"), None);
1931 step.claim_now();
1932 assert_eq!(ctx.mint_id().positional(), "2", "only the step claimed");
1933 assert_eq!(step.await.expect("the step succeeds"), 1);
1934 }
1935
1936 /// A panic inside a `.spawn()`ed operation body must surface to the
1937 /// awaiter as the ORIGINAL panic (payload intact), exactly like the lazy
1938 /// path, not as a fabricated "spawned task was cancelled" step error.
1939 #[tokio::test]
1940 async fn spawned_panic_propagates_original_payload() {
1941 let ctx = test_ctx_with_client();
1942 let fut: DurableFuture<i32> = ctx.step(|_| async { panic!("kaboom-spawn") }).spawn();
1943
1944 // Await on a dedicated task so the re-raised panic is observable as
1945 // a JoinError instead of unwinding the test itself.
1946 let join_err = tokio::spawn(fut).await.unwrap_err();
1947 assert!(join_err.is_panic(), "panic must stay a panic: {join_err}");
1948 let payload = join_err.into_panic();
1949 let msg = payload
1950 .downcast_ref::<&str>()
1951 .map(|s| (*s).to_owned())
1952 .or_else(|| payload.downcast_ref::<String>().cloned())
1953 .unwrap_or_default();
1954 assert!(
1955 msg.contains("kaboom-spawn"),
1956 "original panic payload must be preserved, got: {msg}"
1957 );
1958 }
1959
1960 /// A context created outside every runtime has no invocation runtime.
1961 /// `spawn_started` called later inside a current-thread runtime still
1962 /// refuses: `start` is not called, and the handle resolves to the
1963 /// no-runtime error.
1964 #[test]
1965 fn spawn_started_with_current_runtime_but_no_invocation_runtime_does_not_start() {
1966 let ctx = test_ctx_with_client();
1967 let runtime = tokio::runtime::Builder::new_current_thread()
1968 .enable_all()
1969 .build()
1970 .expect("a runtime builds");
1971 let started = Arc::new(AtomicBool::new(false));
1972 let flag = Arc::clone(&started);
1973 let error = runtime.block_on(async move {
1974 let handle: DurableFuture<u32> = DurableFuture::spawn_started(&ctx, None, move || {
1975 flag.store(true, Ordering::SeqCst);
1976 DurableFuture::from_async(async { Ok(1_u32) })
1977 });
1978 handle.await.expect_err("no invocation runtime").to_string()
1979 });
1980 assert!(!started.load(Ordering::SeqCst), "start must not be called");
1981 let expected = crate::task::NoRuntime::operation_error(crate::task::NoRuntime).to_string();
1982 assert_eq!(error, expected);
1983 }
1984
1985 /// `.spawn()` on a thread with no Tokio runtime resolves to the error
1986 /// the task-ownership check would return, records nothing, and never
1987 /// runs the body.
1988 #[tokio::test]
1989 async fn spawn_outside_runtime_returns_error() {
1990 let client = Arc::new(crate::client::InMemoryExecutionClient::new(Vec::new()));
1991 let ran = Arc::new(AtomicBool::new(false));
1992 let thread_client = Arc::clone(&client);
1993 let thread_ran = Arc::clone(&ran);
1994 // The context is built on the polling thread, so that thread owns it.
1995 let polled = crate::task::test_support::poll_once_without_runtime(move || {
1996 DurableContext::new_root_with_client(
1997 "arn:aws:lambda:us-east-1:1:function:test".to_owned(),
1998 lambda_runtime::Context::default(),
1999 Arc::new(CheckpointLog::empty()),
2000 thread_client as Arc<dyn crate::client::ExecutionClient>,
2001 "token0".to_owned(),
2002 )
2003 .step(move |_| async move {
2004 thread_ran.store(true, Ordering::SeqCst);
2005 Ok(1_i32)
2006 })
2007 .spawn()
2008 });
2009 let Poll::Ready(Err(err)) = polled else {
2010 panic!("expected an immediate error, got {polled:?}");
2011 };
2012 let crate::error::OperationErrorKind::Step(step_err) = err.kind() else {
2013 panic!(
2014 "expected the task-ownership error kind, got {:?}",
2015 err.kind()
2016 );
2017 };
2018 assert!(matches!(
2019 step_err.kind(),
2020 crate::error::StepErrorKind::ExecutionFailed
2021 ));
2022 assert!(
2023 format!("{err:#}").contains(crate::task::NO_RUNTIME_MESSAGE),
2024 "unexpected error: {err:#}"
2025 );
2026 assert!(!ran.load(Ordering::SeqCst), "the body must not run");
2027 assert!(client.recorded_updates().is_empty(), "nothing is recorded");
2028 }
2029
2030 /// Dropping the handle of a `.spawn()`ed operation does not cancel the
2031 /// spawned task: the body keeps running. The task stops, without
2032 /// unwinding anything into the caller, when the tracker aborts it.
2033 #[tokio::test]
2034 async fn dropped_spawned_future_keeps_task_running_without_panic() {
2035 #[derive(Clone)]
2036 struct DropGuard(Arc<AtomicBool>);
2037 impl Drop for DropGuard {
2038 fn drop(&mut self) {
2039 self.0.store(true, Ordering::SeqCst);
2040 }
2041 }
2042
2043 let ctx = test_ctx_with_client();
2044 let dropped = Arc::new(AtomicBool::new(false));
2045 let started = Arc::new(AtomicBool::new(false));
2046 // The guard lives in the closure environment, so the body and the
2047 // guard drop together.
2048 let guard = DropGuard(Arc::clone(&dropped));
2049 let body_started = Arc::clone(&started);
2050
2051 let fut: DurableFuture<i32> = ctx
2052 .step(move |_| async move {
2053 let _guard = guard;
2054 body_started.store(true, Ordering::SeqCst);
2055 std::future::pending::<()>().await;
2056 Ok(0)
2057 })
2058 .spawn();
2059 drop(fut);
2060
2061 for _ in 0..50 {
2062 if started.load(Ordering::SeqCst) {
2063 break;
2064 }
2065 tokio::time::sleep(std::time::Duration::from_millis(10)).await;
2066 }
2067 assert!(
2068 started.load(Ordering::SeqCst),
2069 "the body runs after the drop"
2070 );
2071 assert!(
2072 !dropped.load(Ordering::SeqCst),
2073 "the dropped handle does not cancel the body"
2074 );
2075 let tasks = Arc::clone(ctx.coordinator().tasks());
2076 tasks.abort_all();
2077 tasks.wait_idle().await;
2078 assert!(dropped.load(Ordering::SeqCst), "abort_all cancels the body");
2079 }
2080
2081 #[test]
2082 fn handle_of_a_set_that_never_ran() {
2083 let mut set = BranchSet::new();
2084 let handle = set.add("inventory", |_ctx| async { Ok(1_u32) });
2085 drop(set);
2086 let Err(err) = handle.into_result() else {
2087 panic!("a handle whose set never ran has no result");
2088 };
2089 let crate::OperationErrorKind::ChildContext(child) = err.kind() else {
2090 panic!("the error is a child context error: {err:?}");
2091 };
2092 assert!(matches!(
2093 child.kind(),
2094 crate::ChildContextErrorKind::NotCompleted
2095 ));
2096 assert_eq!(child.kind().to_string(), "branch has no result");
2097 let source = std::error::Error::source(child).expect("the error has a source");
2098 assert_eq!(
2099 source.to_string(),
2100 r#"parallel branch "inventory" has no result"#
2101 );
2102 }
2103
2104 #[test]
2105 fn empty_branch_name_records_the_default_name() {
2106 let mut set = BranchSet::default();
2107 let handle = set.add("", |_ctx| async { Ok(1_u32) });
2108 drop(set);
2109 let err = handle.into_result().expect_err("no result");
2110 let source = std::error::Error::source(&err)
2111 .and_then(std::error::Error::source)
2112 .map(ToString::to_string);
2113 assert_eq!(
2114 source.as_deref(),
2115 Some(r#"parallel branch "parallel-branch-0" has no result"#)
2116 );
2117 }
2118
2119 #[test]
2120 fn branch_set_and_handle_debug() {
2121 let mut set = BranchSet::new();
2122 assert_eq!(format!("{set:?}"), "BranchSet { names: [], .. }");
2123 let handle = set.add("a", |_ctx| async { Ok(1_u32) });
2124 let _other = set.add_with_serdes("b", crate::JsonSerdes, |_ctx| async { Ok(2_u32) });
2125 assert_eq!(format!("{set:?}"), r#"BranchSet { names: ["a", "b"], .. }"#);
2126 assert_eq!(
2127 format!("{handle:?}"),
2128 r#"BranchHandle { name: "a", has_result: false, .. }"#
2129 );
2130 *lock_slot(&handle.slot) = Some(Ok(1));
2131 assert_eq!(
2132 format!("{handle:?}"),
2133 r#"BranchHandle { name: "a", has_result: true, .. }"#
2134 );
2135 }
2136
2137 /// Whether two keys name the same branch of the same set.
2138 fn same_branch<T>(a: &BranchKey<T>, b: &BranchKey<T>) -> bool {
2139 Arc::ptr_eq(&a.identity, &b.identity) && a.index == b.index
2140 }
2141
2142 #[test]
2143 fn branch_keys_name_their_branch_and_set() {
2144 fn assert_clone_send_sync<K: Clone + Send + Sync>() {}
2145 assert_clone_send_sync::<BranchKey<std::cell::Cell<String>>>();
2146
2147 let mut first = BranchSet::new();
2148 let a = first.add("a", |_ctx| async { Ok(1_u32) });
2149 let b = first.add("b", |_ctx| async { Ok(2_u32) });
2150 let mut second = BranchSet::new();
2151 let other_a = second.add("a", |_ctx| async { Ok(1_u32) });
2152
2153 assert!(same_branch(&a.key(), &a.key()));
2154 assert!(same_branch(&a.key(), &a.key().clone()));
2155 assert!(!same_branch(&a.key(), &b.key()));
2156 assert!(!same_branch(&a.key(), &other_a.key()));
2157 assert_eq!(format!("{:?}", b.key()), "BranchKey { index: 1, .. }");
2158 }
2159}