Best Practices & Performance
Best Practices
1. Use Durable Timers, Not Polling
Durable timers are Orcher's most resource-efficient primitive. A sleeping workflow consumes zero CPU and minimal storage — just a single database row. Never implement delays by polling in a tight loop, which wastes resources and creates unnecessary load on your task infrastructure.
1// Good - Durable timer: zero resource consumption while waiting2ctx.sleep(Duration::from_secs(3600)).await?;3ctx.execute_task(check_status, id.clone()).await?;45// Bad - Polling wastes resources and creates unnecessary task executions6loop {7 let status: Status = ctx.execute_task(check_status, id.clone()).await?;8 if status.is_ready() {9 break;10 }11 // Still running during sleep - wastes resources!12 tokio::time::sleep(Duration::from_secs(10)).await;13}2. Set Reasonable Timeouts
Every human interaction or external event wait should have a timeout. Without one, a workflow can block indefinitely if the expected signal never arrives. Choose timeouts that match your business SLA — 48 hours for an approval, 30 minutes for a payment, 7 days for document upload — and always handle the timeout case with an escalation path or default action.
1// Good - Timeout prevents infinite wait2let approval: Option<ApprovalDecision> = ctx3 .wait_for_event_with_timeout("approval", Duration::from_secs(172800))4 .await?;56match approval {7 Some(decision) => handle_approval(decision),8 None => escalate_or_reject(),9}1011// Bad - No timeout, could wait forever12let approval: ApprovalDecision = ctx.wait_for_event("approval").await?;3. Track Progress with Checkpoints
For workflows that span hours or days, recording progress at key milestones gives you observability into where each workflow stands. This is invaluable for debugging, customer support, and operational dashboards. Store checkpoints as workflow state so they're queryable from outside the workflow.
1// Good - Track progress at each milestone2let mut state = ProcessState::new();34state.checkpoints.push("started");5ctx.set_state("process_state", &state).await?;67// ... do work ...89state.checkpoints.push("halfway_complete");10ctx.set_state("process_state", &state).await?;4. Handle Long Wait Failures
When a long-running wait times out, don't just fail the workflow. Build graceful degradation into your timeout handling: send a reminder, extend the deadline, escalate to a manager, or fall back to a default action. This keeps the business process moving even when humans are slow to respond.
1// Good - Graceful handling with reminder and extended deadline2let payment: Option<Payment> = ctx3 .wait_for_event_with_timeout("payment", Duration::from_secs(1800))4 .await?;56match payment {7 Some(payment) => process_payment(payment).await?,8 None => {9 // Timeout - send reminder and extend deadline10 ctx.execute_task(send_payment_reminder, user_id.clone()).await?;1112 let extended_payment: Option<Payment> = ctx13 .wait_for_event_with_timeout("payment", Duration::from_secs(3600))14 .await?;1516 match extended_payment {17 Some(p) => process_payment(p).await?,18 None => cancel_order().await?,19 }20 }21}5. Use Appropriate Time Scales
When writing sleep durations, prefer named constants or comments that make the intended duration immediately obvious. Raw numbers like 1209600 are hard to review and easy to get wrong. Rust's Duration::from_secs with clear comments is far more maintainable than Duration::from_millis with large numbers.
1// Good - Clear, readable durations2ctx.sleep(Duration::from_secs(3600)).await?; // 1 hour3ctx.sleep(Duration::from_secs(86400)).await?; // 1 day4ctx.sleep(Duration::from_secs(604800)).await?; // 1 week56// Bad - Confusing large numbers without context7ctx.sleep(Duration::from_millis(3600000)).await?; // What is this?8ctx.sleep(Duration::from_secs(1209600)).await?; // Hard to read6. Consider Time Zones
When your workflow needs to execute at a specific wall-clock time (e.g., "send at 9 AM Eastern"), you must compute the sleep duration relative to the target time in the correct timezone. Simply sleeping for a fixed number of hours won't account for DST transitions or timezone offsets.
1// Good - Explicit timezone handling2use chrono::{DateTime, Utc, TimeZone};3use chrono_tz::America::New_York;45// Schedule for 9 AM Eastern Time6let target_time = New_York7 .ymd(2024, 1, 15)8 .and_hms(9, 0, 0)9 .with_timezone(&Utc);1011let now = Utc::now();12let wait_duration = (target_time - now).to_std()?;1314ctx.sleep(wait_duration).await?;Performance Considerations
Timer Storage
Each durable timer creates a single database entry with minimal overhead (less than 1KB). Timers are indexed for efficient firing and consume no CPU or memory while waiting. As a rule of thumb, timers are very cheap — use them freely for any delay, whether it's 5 minutes or 5 weeks.
Concurrent Long-Running Workflows
Orcher efficiently handles large numbers of concurrent long-running workflows because sleeping workflows consume almost no resources. The primary constraint is database storage for timer entries and journal rows.
| Concurrent Workflows | Memory Usage | Database Load |
|---|---|---|
| 1,000 | Minimal | Low |
| 10,000 | Low | Low |
| 100,000 | Moderate | Moderate |
| 1,000,000+ | Carefully tune | Carefully tune |
Wake-Up Latency
Timer wake-up latency depends on the timer duration and the polling interval of Orcher's internal timer subsystem. For most use cases, the latency is negligible relative to the timer duration itself.
| Timer Duration | Wake-Up Latency | Use Case |
|---|---|---|
| < 1 minute | ±1 second | Short delays |
| 1-60 minutes | ±5 seconds | Moderate delays |
| 1-24 hours | ±30 seconds | Daily tasks |
| > 24 hours | ±2 minutes | Long-term processes |
Common Patterns Summary
This table summarizes the most common long-running process patterns and their typical durations to help you choose the right approach for your use case.
| Pattern | Duration | Use Case | Example |
|---|---|---|---|
| Short Delay | Minutes | Rate limiting, retries | Wait 5 minutes, retry |
| Human Approval | Hours to Days | Reviews, decisions | Wait 48 hours for approval |
| Trial Period | Days to Weeks | Free trials, subscriptions | 14-day trial period |
| Order Fulfillment | Days | Multi-stage processes | 3-7 day delivery |
| Recurring Task | Hours to Days | Scheduled reports, cleanup | Daily at midnight |
| Reminder Series | Days to Weeks | User engagement | Day 1, 3, 7 reminders |
| Timeout Pattern | Minutes to Hours | External system waits | 30-minute payment timeout |
Real-World Use Cases
These diagrams show how long-running workflows map to real business processes that span days or weeks. Each step in the timeline corresponds to a durable timer sleep, a task execution, or an event wait in the workflow code.
Employee Onboarding
1Onboarding Workflow (30 days)2├─ Day 0: Send welcome email3├─ Day 1: Create accounts4├─ Day 1: Wait for document upload (timeout: 7 days)5├─ Day 3: Send orientation reminder6├─ Day 7: First week check-in7├─ Day 14: Mid-month review8├─ Day 30: Onboarding complete surveySubscription Lifecycle
1Subscription Workflow (12 months)2├─ Day 0: Trial starts3├─ Day 7: Trial reminder4├─ Day 14: Trial expires → Convert or cancel5├─ Month 1-11: Monthly billing6├─ Day 330: Renewal reminder7├─ Day 365: Renewal or cancellationLoan Application
1Loan Processing (14-30 days)2├─ Day 0: Application submitted3├─ Day 1: Wait for documents (timeout: 7 days)4├─ Day 2: Credit check5├─ Day 3: Wait for approval (timeout: 5 days)6├─ Day 5: Approved → Wait for signature (timeout: 10 days)7├─ Day 10: DisbursementContent Publishing Schedule
1Content Schedule (7 days ahead)2├─ Day -7: Draft created3├─ Day -5: First review4├─ Day -3: Revisions5├─ Day -1: Final approval6├─ Day 0: Publish at 9 AM7├─ Day 0: Social media promotion8├─ Day 1: Performance metrics