Skip to main content

pipeline_toolkit/
iteration.rs

1use std::any::TypeId;
2
3use crate::Context;
4use crate::branch::Arm;
5use crate::context::AccessSpec;
6use crate::pipeline::{
7    BuildError, NestedPipelineError, PipelineError, qualify_step_name, run_steps,
8};
9use crate::step::{Flow, Step, StepError};
10
11/// A `Loop`'s condition function, boxed so [`Loop`]/[`LoopBuilder`] don't
12/// need to be generic over it.
13type Condition = Box<dyn Fn(&Context, u32) -> bool + Send + Sync>;
14
15/// A framework-provided [`Step`] that runs the same [`Arm`] body repeatedly,
16/// do-while style, until a condition function says to stop or
17/// `max_iterations` is reached.
18///
19/// Build one via [`Self::builder`]. Unlike [`Branch`](crate::Branch), which
20/// picks one of several arms, `Loop` has exactly one body arm and runs it
21/// one or more times against the same [`Context`].
22///
23/// # Evaluation order
24///
25/// The body always runs at least once. After each run, if the body returned
26/// [`Flow::Done`], that value is produced immediately, short-circuiting the
27/// loop (and the whole pipeline) just like a top-level step would. If the
28/// body returned [`Flow::Continue`], the condition function is called with
29/// the [`Context`] and the 1-based iteration number just completed; a
30/// `false` result stops the loop (`Loop::run` itself then returns
31/// [`Flow::Continue`], handing off to whatever follows the loop in the
32/// enclosing pipeline), while `true` runs the body again. If the condition
33/// never returns `false` within `max_iterations` runs,
34/// [`PipelineError::MaxIterationsExceeded`](crate::PipelineError::MaxIterationsExceeded)
35/// is returned instead.
36///
37/// A body `Err` is never passed to the condition function — it propagates
38/// immediately as an ordinary step failure, the same as any other step's
39/// error. See the [design doc](https://github.com/ryoshrimp/pipeline-toolkit/blob/main/docs/design/iteration.md)
40/// for the rationale (in particular, why retry-worthy failures must be
41/// signalled through the `Context` rather than through `Err`).
42///
43/// # Access declaration
44///
45/// A `Loop`'s [`Step::access`] is computed automatically from its body (plus
46/// the condition function's own declared reads, via
47/// [`LoopBuilder::reads`]) — unlike [`Branch`](crate::Branch), no
48/// union/intersection is needed, since a `Loop` has only one body and that
49/// body is guaranteed (see [`Self::builder`]) to leave its own effective
50/// access stable across repeated runs:
51///
52/// - **reads** = the body's effective reads + the condition's declared reads
53/// - **writes** = the body's effective writes
54/// - **consumes** = the body's effective consumes
55///
56/// # Examples
57///
58/// ```
59/// use pipeline_toolkit::{AccessSpec, Arm, Context, Flow, Loop, Pipeline, Step, StepError};
60///
61/// struct Counter(i32);
62///
63/// struct Increment;
64///
65/// #[async_trait::async_trait]
66/// impl Step<i32> for Increment {
67///     fn name(&self) -> &str {
68///         "increment"
69///     }
70///     fn access(&self) -> AccessSpec {
71///         AccessSpec::new().reads_writes::<Counter>()
72///     }
73///     async fn run(&self, ctx: &mut Context) -> Result<Flow<i32>, StepError> {
74///         ctx.get_mut::<Counter>().expect("declared as reads_writes").0 += 1;
75///         Ok(Flow::Continue)
76///     }
77/// }
78///
79/// let body = Arm::builder().step(Increment).build()?;
80/// let count_to_three = Loop::builder(
81///     "count_to_three",
82///     body,
83///     |ctx: &Context, _iteration: u32| ctx.get::<Counter>().expect("declared as read").0 < 3,
84///     10,
85/// )
86/// .reads::<Counter>()
87/// .build()?;
88///
89/// struct Init;
90/// #[async_trait::async_trait]
91/// impl Step<i32> for Init {
92///     fn name(&self) -> &str {
93///         "init"
94///     }
95///     fn access(&self) -> AccessSpec {
96///         AccessSpec::new().writes::<Counter>()
97///     }
98///     async fn run(&self, ctx: &mut Context) -> Result<Flow<i32>, StepError> {
99///         ctx.insert(Counter(0));
100///         Ok(Flow::Continue)
101///     }
102/// }
103///
104/// struct Finish;
105/// #[async_trait::async_trait]
106/// impl Step<i32> for Finish {
107///     fn name(&self) -> &str {
108///         "finish"
109///     }
110///     fn access(&self) -> AccessSpec {
111///         AccessSpec::new().reads::<Counter>()
112///     }
113///     async fn run(&self, ctx: &mut Context) -> Result<Flow<i32>, StepError> {
114///         Ok(Flow::Done(ctx.get::<Counter>().expect("declared as read").0))
115///     }
116/// }
117///
118/// let pipeline = Pipeline::<(), i32>::builder()
119///     .step(Init)
120///     .step(count_to_three)
121///     .step(Finish)
122///     .build()?;
123///
124/// # fn block_on<F: std::future::Future>(fut: F) -> F::Output {
125/// #     use std::task::{Context as TaskContext, Poll, Waker};
126/// #     let mut fut = std::pin::pin!(fut);
127/// #     let mut cx = TaskContext::from_waker(Waker::noop());
128/// #     loop {
129/// #         if let Poll::Ready(val) = fut.as_mut().poll(&mut cx) {
130/// #             return val;
131/// #         }
132/// #     }
133/// # }
134/// #
135/// assert_eq!(block_on(pipeline.run(()))?, 3);
136/// # Ok::<(), Box<dyn std::error::Error>>(())
137/// ```
138pub struct Loop<Out> {
139    name: String,
140    body: Arm<Out>,
141    condition: Condition,
142    max_iterations: u32,
143    access: AccessSpec,
144}
145
146impl<Out> Loop<Out> {
147    /// Starts building a `Loop` named `name`, whose body is `body` and whose
148    /// continuation is decided by calling `condition` against the shared
149    /// [`Context`] and the 1-based number of the iteration just completed,
150    /// after every run of `body` that returns [`Flow::Continue`].
151    ///
152    /// `max_iterations` is the upper bound on how many times `body` may run
153    /// before [`Loop::run`] gives up with
154    /// [`PipelineError::MaxIterationsExceeded`](crate::PipelineError::MaxIterationsExceeded).
155    /// It's a required constructor argument rather than a builder default,
156    /// since an unbounded loop is a production hazard (hang, resource leak)
157    /// that's cheap to guard against statically.
158    ///
159    /// If `condition` itself reads from the [`Context`], declare that via
160    /// [`LoopBuilder::reads`] — it is not inferred automatically, since a
161    /// closure's body can't be introspected.
162    pub fn builder(
163        name: impl Into<String>,
164        body: Arm<Out>,
165        condition: impl Fn(&Context, u32) -> bool + Send + Sync + 'static,
166        max_iterations: u32,
167    ) -> LoopBuilder<Out> {
168        LoopBuilder {
169            name: name.into(),
170            body,
171            condition: Box::new(condition),
172            condition_access: AccessSpec::new(),
173            max_iterations,
174        }
175    }
176}
177
178#[async_trait::async_trait]
179impl<Out> Step<Out> for Loop<Out>
180where
181    Out: Send + Sync + 'static,
182{
183    fn name(&self) -> &str {
184        &self.name
185    }
186
187    fn access(&self) -> AccessSpec {
188        self.access.clone()
189    }
190
191    async fn run(&self, ctx: &mut Context) -> Result<Flow<Out>, StepError> {
192        for iteration in 1..=self.max_iterations {
193            match run_steps(self.body.steps(), ctx).await {
194                Ok(Flow::Done(out)) => return Ok(Flow::Done(out)),
195                Ok(Flow::Continue) => {
196                    if !(self.condition)(ctx, iteration) {
197                        return Ok(Flow::Continue);
198                    }
199                }
200                Err(err) => {
201                    return Err(StepError::new(NestedPipelineError(qualify_step_name(
202                        &self.name, err,
203                    ))));
204                }
205            }
206        }
207        Err(StepError::new(NestedPipelineError(
208            PipelineError::MaxIterationsExceeded {
209                step: self.name.clone(),
210                max_iterations: self.max_iterations,
211            },
212        )))
213    }
214}
215
216/// Incrementally assembles a [`Loop`], returned by [`Loop::builder`].
217pub struct LoopBuilder<Out> {
218    name: String,
219    body: Arm<Out>,
220    condition: Condition,
221    condition_access: AccessSpec,
222    max_iterations: u32,
223}
224
225impl<Out> LoopBuilder<Out> {
226    /// Declares that the condition function reads `T` from the [`Context`]
227    /// when it runs, folding it into the reads computed for
228    /// [`Step::access`]. Chainable across multiple types, like
229    /// [`AccessSpec::reads`].
230    pub fn reads<T: 'static>(mut self) -> Self {
231        self.condition_access = self.condition_access.reads::<T>();
232        self
233    }
234
235    /// Finishes this `Loop`, computing its [`Step::access`] from the body's
236    /// effective access plus the condition's own declared reads.
237    ///
238    /// # Errors
239    ///
240    /// - [`BuildError::UnrepeatableConsume`] if the body consumes (via
241    ///   [`AccessSpec::consumes`]) a type it doesn't also write again by the
242    ///   time it finishes — such a body would work on the first iteration
243    ///   but find that type gone on the second, since the same body runs
244    ///   more than once.
245    pub fn build(self) -> Result<Loop<Out>, BuildError> {
246        let effective = self.body.effective_access();
247        let mut missing: Vec<(TypeId, &'static str)> = effective
248            .consumes
249            .iter()
250            .filter(|(id, _)| !effective.writes.contains_key(id))
251            .map(|(id, name)| (*id, *name))
252            .collect();
253        if !missing.is_empty() {
254            missing.sort_unstable_by_key(|(_, name)| *name);
255            let (_, entry) = missing[0];
256            return Err(BuildError::UnrepeatableConsume {
257                step: self.name,
258                entry,
259            });
260        }
261
262        let mut access = self.condition_access;
263        access.extend_reads(effective.reads.iter().map(|(id, name)| (*id, *name)));
264        access.extend_writes(effective.writes.iter().map(|(id, name)| (*id, *name)));
265        // A type that's also in `effective.writes` is guaranteed present
266        // once the body finishes (the `UnrepeatableConsume` check above
267        // ensures every consumed type meets this), so it must not be
268        // declared as consumed here too: PipelineBuilder::build applies a
269        // step's declared writes before its declared consumes, so a type
270        // present in both would have its guaranteed write immediately
271        // undone by the same step's own consume, making the outer pipeline
272        // wrongly see it as unavailable to a step downstream of this Loop.
273        access.extend_consumes(
274            effective
275                .consumes
276                .iter()
277                .filter(|(id, _)| !effective.writes.contains_key(id))
278                .map(|(id, name)| (*id, *name)),
279        );
280
281        Ok(Loop {
282            name: self.name,
283            body: self.body,
284            condition: self.condition,
285            max_iterations: self.max_iterations,
286            access,
287        })
288    }
289}
290
291#[cfg(test)]
292mod test {
293    use super::*;
294    use crate::step::Flow;
295    use crate::test_support::block_on;
296
297    struct Counter(i32);
298
299    struct Increment;
300
301    #[async_trait::async_trait]
302    impl Step<i32> for Increment {
303        fn name(&self) -> &str {
304            "increment"
305        }
306        fn access(&self) -> AccessSpec {
307            AccessSpec::new().reads_writes::<Counter>()
308        }
309        async fn run(&self, ctx: &mut Context) -> Result<Flow<i32>, StepError> {
310            ctx.get_mut::<Counter>()
311                .expect("declared as reads_writes")
312                .0 += 1;
313            Ok(Flow::Continue)
314        }
315    }
316
317    fn increment_body() -> Arm<i32> {
318        Arm::builder().step(Increment).build().unwrap()
319    }
320
321    fn less_than(limit: i32) -> impl Fn(&Context, u32) -> bool + Send + Sync + 'static {
322        move |ctx: &Context, _iteration: u32| {
323            ctx.get::<Counter>().expect("declared as read").0 < limit
324        }
325    }
326
327    #[test]
328    fn build_fails_when_body_consumes_a_type_it_never_rewrites() {
329        struct Token;
330
331        struct ConsumeToken;
332        #[async_trait::async_trait]
333        impl Step<i32> for ConsumeToken {
334            fn name(&self) -> &str {
335                "consume_token"
336            }
337            fn access(&self) -> AccessSpec {
338                AccessSpec::new().consumes::<Token>()
339            }
340            async fn run(&self, ctx: &mut Context) -> Result<Flow<i32>, StepError> {
341                ctx.take::<Token>();
342                Ok(Flow::Continue)
343            }
344        }
345
346        let body = Arm::<i32>::builder().step(ConsumeToken).build().unwrap();
347        let result = Loop::builder("loop", body, |_ctx: &Context, _i: u32| false, 5).build();
348        assert!(matches!(
349            result,
350            Err(BuildError::UnrepeatableConsume { step, .. }) if step == "loop"
351        ));
352    }
353
354    #[test]
355    fn build_succeeds_when_body_rewrites_a_type_it_consumed() {
356        struct Token;
357
358        struct ConsumeToken;
359        #[async_trait::async_trait]
360        impl Step<i32> for ConsumeToken {
361            fn name(&self) -> &str {
362                "consume_token"
363            }
364            fn access(&self) -> AccessSpec {
365                AccessSpec::new().consumes::<Token>()
366            }
367            async fn run(&self, ctx: &mut Context) -> Result<Flow<i32>, StepError> {
368                ctx.take::<Token>();
369                Ok(Flow::Continue)
370            }
371        }
372
373        struct RewriteToken;
374        #[async_trait::async_trait]
375        impl Step<i32> for RewriteToken {
376            fn name(&self) -> &str {
377                "rewrite_token"
378            }
379            fn access(&self) -> AccessSpec {
380                AccessSpec::new().writes::<Token>()
381            }
382            async fn run(&self, ctx: &mut Context) -> Result<Flow<i32>, StepError> {
383                ctx.insert(Token);
384                Ok(Flow::Continue)
385            }
386        }
387
388        let body = Arm::<i32>::builder()
389            .step(ConsumeToken)
390            .step(RewriteToken)
391            .build()
392            .unwrap();
393        let result = Loop::builder("loop", body, |_ctx: &Context, _i: u32| false, 5).build();
394        assert!(result.is_ok());
395    }
396
397    #[test]
398    fn run_executes_body_the_correct_number_of_times_until_condition_is_false() {
399        let body = increment_body();
400        let looped = Loop::builder("loop", body, less_than(3), 10)
401            .reads::<Counter>()
402            .build()
403            .unwrap();
404
405        let mut ctx = Context::new();
406        ctx.insert(Counter(0));
407        let result = block_on(looped.run(&mut ctx));
408        assert!(matches!(result, Ok(Flow::Continue)));
409        assert_eq!(ctx.get::<Counter>().unwrap().0, 3);
410    }
411
412    #[test]
413    fn run_fails_with_max_iterations_exceeded_when_condition_never_becomes_false() {
414        let body = increment_body();
415        let looped = Loop::builder("loop", body, |_ctx: &Context, _i: u32| true, 3)
416            .build()
417            .unwrap();
418
419        let mut ctx = Context::new();
420        ctx.insert(Counter(0));
421        let err = match block_on(looped.run(&mut ctx)) {
422            Err(err) => err,
423            Ok(_) => panic!("expected Err"),
424        };
425        let nested = err
426            .downcast::<NestedPipelineError>()
427            .unwrap_or_else(|_| panic!("expected a NestedPipelineError"));
428        match nested.0 {
429            PipelineError::MaxIterationsExceeded {
430                step,
431                max_iterations,
432            } => {
433                assert_eq!(step, "loop");
434                assert_eq!(max_iterations, 3);
435            }
436            other => panic!("expected MaxIterationsExceeded, got {other}"),
437        }
438        assert_eq!(ctx.get::<Counter>().unwrap().0, 3);
439    }
440
441    #[test]
442    fn run_propagates_a_body_err_immediately_without_consulting_the_condition() {
443        struct Fail;
444        #[async_trait::async_trait]
445        impl Step<i32> for Fail {
446            fn name(&self) -> &str {
447                "fail"
448            }
449            fn access(&self) -> AccessSpec {
450                AccessSpec::new()
451            }
452            async fn run(&self, _ctx: &mut Context) -> Result<Flow<i32>, StepError> {
453                Err(StepError::new("boom"))
454            }
455        }
456
457        let body = Arm::<i32>::builder().step(Fail).build().unwrap();
458        let looped = Loop::builder(
459            "loop",
460            body,
461            |_ctx: &Context, _i: u32| {
462                panic!("condition must not be consulted when the body errors")
463            },
464            5,
465        )
466        .build()
467        .unwrap();
468
469        let mut ctx = Context::new();
470        let err = match block_on(looped.run(&mut ctx)) {
471            Err(err) => err,
472            Ok(_) => panic!("expected Err"),
473        };
474        let nested = err
475            .downcast::<NestedPipelineError>()
476            .unwrap_or_else(|_| panic!("expected a NestedPipelineError"));
477        match nested.0 {
478            PipelineError::Step { step, .. } => assert_eq!(step, "loop/fail"),
479            other => panic!("expected Step, got {other}"),
480        }
481    }
482
483    #[test]
484    fn run_propagates_a_body_done_to_the_outer_caller() {
485        struct DoneStep(i32);
486        #[async_trait::async_trait]
487        impl Step<i32> for DoneStep {
488            fn name(&self) -> &str {
489                "done"
490            }
491            fn access(&self) -> AccessSpec {
492                AccessSpec::new()
493            }
494            async fn run(&self, _ctx: &mut Context) -> Result<Flow<i32>, StepError> {
495                Ok(Flow::Done(self.0))
496            }
497        }
498
499        let body = Arm::<i32>::builder().step(DoneStep(99)).build().unwrap();
500        let looped = Loop::builder(
501            "loop",
502            body,
503            |_ctx: &Context, _i: u32| {
504                panic!("condition must not be consulted when the body is Done")
505            },
506            5,
507        )
508        .build()
509        .unwrap();
510
511        let mut ctx = Context::new();
512        match block_on(looped.run(&mut ctx)) {
513            Ok(Flow::Done(v)) => assert_eq!(v, 99),
514            Ok(Flow::Continue) => panic!("expected Done(99), got Continue"),
515            Err(err) => panic!("expected Done(99), got Err({err})"),
516        }
517    }
518
519    #[test]
520    fn run_passes_the_1_based_iteration_number_to_the_condition() {
521        use std::sync::{Arc, Mutex};
522
523        let seen = Arc::new(Mutex::new(Vec::new()));
524        let seen_in_condition = seen.clone();
525
526        let body = increment_body();
527        let looped = Loop::builder(
528            "loop",
529            body,
530            move |_ctx: &Context, iteration: u32| {
531                seen_in_condition.lock().unwrap().push(iteration);
532                iteration < 3
533            },
534            10,
535        )
536        .build()
537        .unwrap();
538
539        let mut ctx = Context::new();
540        ctx.insert(Counter(0));
541        block_on(looped.run(&mut ctx)).unwrap();
542        assert_eq!(*seen.lock().unwrap(), vec![1, 2, 3]);
543    }
544
545    #[test]
546    fn access_reads_is_union_of_body_needed_reads_and_condition_declared_reads() {
547        struct Other;
548        struct ReadsOther;
549        #[async_trait::async_trait]
550        impl Step<i32> for ReadsOther {
551            fn name(&self) -> &str {
552                "reads_other"
553            }
554            fn access(&self) -> AccessSpec {
555                AccessSpec::new().reads::<Other>()
556            }
557            async fn run(&self, _ctx: &mut Context) -> Result<Flow<i32>, StepError> {
558                Ok(Flow::Continue)
559            }
560        }
561
562        let body = Arm::<i32>::builder().step(ReadsOther).build().unwrap();
563        let looped = Loop::builder("loop", body, |_ctx: &Context, _i: u32| false, 5)
564            .reads::<Counter>()
565            .build()
566            .unwrap();
567
568        let access = looped.access();
569        assert!(access.can_read(TypeId::of::<Other>()));
570        assert!(access.can_read(TypeId::of::<Counter>()));
571    }
572
573    #[test]
574    fn access_does_not_declare_consumed_when_the_body_also_rewrites_it() {
575        // LoopBuilder::build's UnrepeatableConsume check (see the
576        // build_fails/build_succeeds tests above) means any type that
577        // survives in the body's effective consumes is, by construction,
578        // also in its effective writes. Declaring it as consumed on the
579        // Loop's own access anyway would be actively wrong, not just
580        // redundant: PipelineBuilder::build applies a step's declared
581        // writes before its declared consumes, so a type present in both
582        // would have its guaranteed write immediately undone by the same
583        // step's own consume - making a step downstream of this Loop that
584        // reads Consumed fail to build even though the Loop always leaves
585        // Consumed behind.
586        struct Written;
587        struct Consumed;
588
589        struct WriteAndConsume;
590        #[async_trait::async_trait]
591        impl Step<i32> for WriteAndConsume {
592            fn name(&self) -> &str {
593                "write_and_consume"
594            }
595            fn access(&self) -> AccessSpec {
596                AccessSpec::new().writes::<Written>().consumes::<Consumed>()
597            }
598            async fn run(&self, _ctx: &mut Context) -> Result<Flow<i32>, StepError> {
599                Ok(Flow::Continue)
600            }
601        }
602        struct RewriteConsumed;
603        #[async_trait::async_trait]
604        impl Step<i32> for RewriteConsumed {
605            fn name(&self) -> &str {
606                "rewrite_consumed"
607            }
608            fn access(&self) -> AccessSpec {
609                AccessSpec::new().writes::<Consumed>()
610            }
611            async fn run(&self, _ctx: &mut Context) -> Result<Flow<i32>, StepError> {
612                Ok(Flow::Continue)
613            }
614        }
615
616        let body = Arm::<i32>::builder()
617            .step(WriteAndConsume)
618            .step(RewriteConsumed)
619            .build()
620            .unwrap();
621        let looped = Loop::builder("loop", body, |_ctx: &Context, _i: u32| false, 5)
622            .build()
623            .unwrap();
624
625        let access = looped.access();
626        assert!(access.can_write(TypeId::of::<Written>()));
627        assert!(access.can_write(TypeId::of::<Consumed>()));
628        assert!(!access.can_consume(TypeId::of::<Consumed>()));
629    }
630}