actionqueue_engine/
lib.rs

1#![forbid(unsafe_code)]
2//! Engine utilities and abstractions for the ActionQueue system.
3//!
4//! This crate provides the scheduling engine for the ActionQueue system, including
5//! run derivation, state management, and scheduling logic.
6//!
7//! # Overview
8//!
9//! The engine crate defines the scheduling logic for the ActionQueue system:
10//!
11//! - [`mod@derive`] - Run derivation from task specifications according to run policies
12//! - [`index`] - Indexing utilities for run instances by state (Scheduled, Ready, Running, Terminal)
13//! - [`selection`] - Run selection for executor leasing
14//! - [`scheduler`] - Scheduling logic for state promotion and ordering
15//! - [`time`] - Time clock abstractions for deterministic testing
16//! - [`lease`] - Lease ownership and expiry models
17//! - [`concurrency`] - Concurrency key gates for single-flight execution control
18//!
19//! # Example
20//!
21//! ```
22//! use actionqueue_core::ids::TaskId;
23//! use actionqueue_core::task::constraints::TaskConstraints;
24//! use actionqueue_core::task::metadata::TaskMetadata;
25//! use actionqueue_core::task::run_policy::RunPolicy;
26//! use actionqueue_core::task::task_spec::{TaskPayload, TaskSpec};
27//! use actionqueue_engine::derive::{derive_runs, DerivationResult};
28//! use actionqueue_engine::time::clock::{Clock, SystemClock};
29//!
30//! // Create a clock for deterministic time management
31//! let clock = SystemClock::default();
32//!
33//! // Create a task with a "Once" run policy
34//! let task_id = TaskId::new();
35//! let task_spec = TaskSpec::new(
36//!     task_id,
37//!     TaskPayload::with_content_type(vec![1, 2, 3], "application/octet-stream"),
38//!     RunPolicy::Once,
39//!     TaskConstraints::default(),
40//!     TaskMetadata::default(),
41//! )
42//! .expect("example task spec should be valid");
43//!
44//! // Derive runs for the task - for "Once" policy, this creates at most one run
45//! let result: DerivationResult = derive_runs(
46//!     &clock,
47//!     task_id,
48//!     task_spec.run_policy(),
49//!     0,           // already_derived
50//!     clock.now(), // schedule_origin
51//! );
52//!
53//! // The result contains newly derived runs
54//! // For a "Once" policy, this will be at most one run
55//! let derived_runs = result.expect("derivation must succeed for valid policy").into_derived();
56//!
57//! // In real usage, the engine indexes would track runs by state:
58//! // - Scheduled: runs waiting for their scheduled_at time
59//! // - Ready: runs ready to be leased to executors
60//! // - Running: runs currently being executed
61//! // - Terminal: completed, failed, or canceled runs
62//!
63//! # // Verify the result is valid (At least one run should be derived)
64//! # assert!(derived_runs.len() <= 1);
65//! ```
66
67pub mod derive;
68pub mod index;
69pub mod lease {
70    //! Lease primitives for deterministic in-flight ownership.
71
72    pub mod acquire;
73    pub mod expiry;
74    pub mod model;
75}
76pub mod concurrency {
77    //! Concurrency key gate primitives for single-flight execution control.
78
79    pub mod key_gate;
80    pub mod lifecycle;
81}
82pub mod scheduler;
83pub mod selection;
84pub mod time;
actionqueue_engine/lib.rs

actionqueue_engine/
lib.rs
