Best Practices & Performance
Best Practices
1. Control Concurrency
Always limit the number of parallel operations to avoid overwhelming downstream systems, exhausting database connections, or running out of memory. Start with a conservative limit (e.g., 50) and tune based on monitoring.
1// Good - Controlled concurrency2const MAX_CONCURRENT: usize = 50;34for chunk in items.chunks(MAX_CONCURRENT) {5 let tasks: Vec<_> = chunk6 .iter()7 .map(|item| ctx.execute_task(process_item, item.clone()))8 .collect();910 for task in tasks {11 results.push(task.await?);12 }13}1415// Bad - Unbounded parallelism (could be 10,000+ items!)16let tasks: Vec<_> = items17 .iter()18 .map(|item| ctx.execute_task(process_item, item.clone()))19 .collect();2. Handle Partial Failures
Don't let one failed item abort the entire batch. Catch errors per-item and collect both successes and failures, giving the caller enough information to retry just the failed items or accept the partial result.
1// Good - Continue on partial failures2for (item_id, task) in task_handles {3 match task.await {4 Ok(result) => successful.push(result),5 Err(e) => {6 eprintln!("Task failed: {}", e);7 failed.push((item_id, e));8 }9 }10}1112// Bad - One failure stops everything13for task in task_handles {14 let result = task.await?; // Aborts at first error15 results.push(result);16}3. Aggregate Results Efficiently
For large result sets, avoid collecting all results into memory before aggregating. Instead, compute running aggregates (sum, count, min, max) as results arrive. This keeps memory usage constant regardless of how many items you process.
1// Good - Stream aggregation (constant memory)2let mut total = 0;3for task in tasks {4 let value = task.await?;5 total += value;6}78// Bad - Collect all then aggregate (memory proportional to item count)9let results: Vec<_> = /* collect all results */;10let total: i32 = results.iter().sum();4. Set Appropriate Timeouts
Each fanned-out task should have a timeout that matches its expected duration. Without timeouts, a single hung task can block the entire fan-in phase indefinitely.
1// Good - Task-appropriate timeout2#[task(name = "api_call", timeout_mins = 1)] // API calls: 1 minute3#[task(name = "batch_import", timeout_mins = 30)] // Imports: 30 minutes45// Bad - Timeout too short for the operation6#[task(name = "long_computation", timeout_mins = 1)] // Actually takes hours!5. Monitor Progress
For long-running fan-out operations, log progress at regular intervals so operators can see how much work remains and estimate completion time.
1// Good - Progress tracking2let total = items.len();3let mut completed = 0;45for task in tasks {6 task.await?;7 completed += 1;8 if completed % 100 == 0 || completed == total {9 println!("Progress: {}/{} ({:.1}%)",10 completed, total, (completed as f64 / total as f64) * 100.0);11 }12}6. Choose Tasks vs Child Workflows
Use tasks for lightweight, fast operations (under a few seconds) and child workflows for complex, multi-step operations that need independent error handling, their own journal, or may take minutes to complete.
1// Good - Tasks for simple, fast operations2for item in items {3 ctx.execute_task(validate_item, item).await?; // Milliseconds4}56// Good - Child workflows for complex operations7for order in orders {8 ctx.start_child_workflow("process_order", order).await?; // Minutes, multi-step9}1011// Bad - Child workflows for trivial operations (unnecessary overhead)12for item in items {13 ctx.start_child_workflow("validate_item", item).await?; // Overkill14}Performance Considerations
Parallelism Limits
The degree of parallelism directly impacts resource usage. Choose a concurrency level appropriate for your workload and downstream system capacity.
| Concurrent Operations | Memory Usage | Network Connections | Recommended For |
|---|---|---|---|
| 1-10 | Minimal | Low | Small batches |
| 10-50 | Low | Moderate | Standard processing |
| 50-100 | Moderate | High | High throughput |
| 100+ | High | Very High | Carefully tune |
Rule of thumb: Start with 50 concurrent operations and tune based on monitoring.
Latency Analysis
Fan-out/fan-in latency is determined by three components: the time to dispatch all tasks (fan-out overhead), the time for the slowest task to complete (parallel execution), and the time to collect results (fan-in overhead).
10 × 100ms — each op waits for the one before it.
10ms fan-out + 100ms slowest op + 1ms fan-in.
Result Collection Strategies
Choose a collection strategy based on the number of results and available memory.
1// Strategy 1: Collect all (good for < 10K results)2let results: Vec<_> = /* await all tasks */;34// Strategy 2: Stream aggregation (good for any size, constant memory)5let mut aggregate = Aggregate::new();6for task in tasks {7 let result = task.await?;8 aggregate.add(result);9}1011// Strategy 3: Batch collection (good for > 10K results)12for chunk in task_handles.chunks(1000) {13 let batch_results = /* await chunk */;14 persist_batch(batch_results).await?;15}Common Patterns Summary
| Pattern | Use Case | Example |
|---|---|---|
| Basic Fan-Out/Fan-In | Independent operations | Parallel API calls |
| Rate-Limited Fan-Out | Protect downstream systems | API with rate limits |
| Partial Failure Handling | Resilient processing | Optional validations |
| Dynamic Fan-Out | Variable workload | Multi-source aggregation |
| Nested Fan-Out | Hierarchical processing | Region → Store → Product |
| Streaming Fan-In | Large result sets | Big data aggregation |