Struct BasicCpmPlanner 

pub struct BasicCpmPlanner { /* private fields */ }

Open-source CPM planner with file-aware locking.

Implementations

impl BasicCpmPlanner

pub fn new() -> Self

Construct a planner with a real-clock and the DEFAULT_TTL. Audit events are dropped on the floor (use Self::with_audit if you need them retained).

pub fn with_audit(audit: Arc<dyn AuditSink>) -> Self

Construct a planner with the supplied audit sink and the default TTL. The real Utc::now is used as the clock.

Examples found in repository

examples/plan_basic.rs (line 71)

async fn main() -> anyhow::Result<()> {
    // ── 1. Build the planner with a capturing audit sink ────────────
    let audit = Arc::new(BufferingAudit::default());
    let planner = BasicCpmPlanner::with_audit(audit.clone());

    // ── 2. Submit a small graph ─────────────────────────────────────
    //
    //   d1 (1h) ─┐
    //            ├─► d3 (2h) ─► d4 (1h)
    //   d2 (3h) ─┘                   ▲
    //                                │
    //                            (critical
    //                             path: d2→d3→d4 = 6h)
    let graph = PlanGraph {
        deliverables: vec![
            deliverable("d1", &["src/a.rs"], &[], 1.0),
            deliverable("d2", &["src/b.rs"], &[], 3.0),
            deliverable("d3", &["src/c.rs"], &["d1", "d2"], 2.0),
            deliverable("d4", &["src/d.rs"], &["d3"], 1.0),
        ],
        max_chained_dispatch: None,
    };
    let plan_id = planner.submit_plan(graph).await?;
    println!("submitted plan: {plan_id}");

    // ── 3. Print the critical path ──────────────────────────────────
    let status = planner.status(&plan_id).await?;
    println!(
        "critical path: {:?} ({:.1}h total)",
        status.critical_path, status.critical_path_hours
    );

    // ── 4. Drive the plan to completion, cohort by cohort ───────────
    let caller = CallerId("demo-orchestrator".to_string());
    let mut round = 0;
    loop {
        round += 1;
        // Acquire up to 4 deliverables. The planner returns only those
        // whose prerequisites are Complete AND whose files don't overlap
        // with anything currently locked.
        let cohort = planner.acquire_cohort(&plan_id, &caller, 4).await?;
        if cohort.rows.is_empty() {
            // Two cases for empty: terminal (everything Complete) or
            // blocked (locks held by someone else, or no Ready work).
            // For this single-caller example, empty means terminal.
            println!("round {round}: no work remaining; plan is terminal.");
            break;
        }
        let ids: Vec<&str> = cohort
            .rows
            .iter()
            .map(|r| r.deliverable.id.as_str())
            .collect();
        println!("round {round}: acquired cohort {ids:?}");

        for row in &cohort.rows {
            planner
                .mark_status(
                    &plan_id,
                    &row.deliverable.id,
                    &caller,
                    DeliverableStatus::Complete,
                )
                .await?;
            println!("  marked {} complete", row.deliverable.id);
        }
    }

    // ── 5. Final status ─────────────────────────────────────────────
    let status = planner.status(&plan_id).await?;
    let complete = status
        .deliverables
        .iter()
        .filter(|(_, s)| matches!(s, DeliverableStatus::Complete))
        .count();
    println!(
        "final state: {complete}/{total} deliverables complete; {locks} locks held",
        total = status.deliverables.len(),
        locks = status.locks_held.len()
    );

    // ── 6. Audit trail ──────────────────────────────────────────────
    let events = audit
        .events
        .lock()
        .map_err(|e| anyhow::anyhow!("audit buffer poisoned: {e}"))?;
    println!("\naudit events ({} total):", events.len());
    for event in events.iter() {
        println!("  - {}", event.event_type);
    }

    Ok(())
}

pub fn with_ttl(self, ttl: Duration) -> Self

Override the lock TTL. Useful for short-lived integration tests.

pub fn with_clock(self, clock: ClockFn) -> Self

Override the clock. Intended for deterministic TTL tests; production code should not call this.

pub fn with_parts( audit: Arc<dyn AuditSink>, ttl: Duration, clock: ClockFn, ) -> Self

Full-parts constructor. Public for clients that want explicit control over every field at once.

Trait Implementations

impl Default for BasicCpmPlanner

fn default() -> Self

Returns the “default value” for a type.

impl Planner for BasicCpmPlanner

fn submit_plan<'life0, 'async_trait>( &'life0 self, graph: PlanGraph, ) -> Pin<Box<dyn Future<Output = Result<PlanId, PlannerError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Submit a PlanGraph. Idempotent on (graph, caller_id); an identical resubmission returns the existing PlanId.

fn acquire_cohort<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, plan_id: &'life1 PlanId, caller_id: &'life2 CallerId, max_count: usize, ) -> Pin<Box<dyn Future<Output = Result<Cohort, PlannerError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Acquire up to max_count deliverables that are ready to run and have mutually disjoint owned_files (within the cohort and against all currently held locks). The returned Cohort carries one crate::plan::LockInfo per acquired deliverable, in the same order.

fn mark_status<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, plan_id: &'life1 PlanId, deliverable_id: &'life2 str, caller_id: &'life3 CallerId, status: DeliverableStatus, ) -> Pin<Box<dyn Future<Output = Result<(), PlannerError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Update the lifecycle state of a deliverable. Setting Complete or Failed releases the lock; caller_id MUST be the lock holder or the call is rejected with PlannerError::LockNotHeld.

fn heartbeat<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, plan_id: &'life1 PlanId, deliverable_id: &'life2 str, caller_id: &'life3 CallerId, ) -> Pin<Box<dyn Future<Output = Result<(), PlannerError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Refresh the TTL on a held lock. Rejected with PlannerError::LockNotHeld if caller_id is not the holder, or with PlannerError::LockExpired if the lock already lapsed.

fn status<'life0, 'life1, 'async_trait>( &'life0 self, plan_id: &'life1 PlanId, ) -> Pin<Box<dyn Future<Output = Result<PlanStatus, PlannerError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Cheap read-only snapshot. Safe to poll on a timer.

fn force_release<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, plan_id: &'life1 PlanId, deliverable_id: &'life2 str, reason: &'life3 str, ) -> Pin<Box<dyn Future<Output = Result<(), PlannerError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Operator escape hatch: forcibly release a lock regardless of holder or TTL. Implementations MUST emit an audit event carrying reason.