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
11type Condition = Box<dyn Fn(&Context, u32) -> bool + Send + Sync>;
14
15pub 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 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
216pub 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 pub fn reads<T: 'static>(mut self) -> Self {
231 self.condition_access = self.condition_access.reads::<T>();
232 self
233 }
234
235 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 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 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}