diff --git a/Cargo.toml b/Cargo.toml index 7baef5e..171d551 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "tasklet" -version = "0.4.0" +version = "0.4.1" authors = ["Stavros Grigoriou "] edition = "2021" rust-version = "1.90.0" diff --git a/README.md b/README.md index f55bced..bfae042 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ In your `Cargo.toml` add: ``` [dependencies] -tasklet = "0.4.0" +tasklet = "0.4.1" ``` To derive `serde` on the observable state types (`TaskState`, `Status`, `RunRecord`, @@ -42,7 +42,7 @@ To derive `serde` on the observable state types (`TaskState`, `Status`, `RunReco ``` [dependencies] -tasklet = { version = "0.4.0", features = ["serde"] } +tasklet = { version = "0.4.1", features = ["serde"] } ``` > **Upgrading from 0.2.x?** See the [migration notes](#migrating-from-02x-to-030) below — @@ -211,6 +211,43 @@ for state in handle.statuses() { See [`examples/overlap_and_status_example.rs`](/examples/overlap_and_status_example.rs) for a runnable demo. +Since 0.4.1, `handle.step_states(id)` reflects step transitions *live* during a run, not +only after it finishes: a completed early step shows as `Succeeded` while a later step is +still `Pending`. + +## Schedule helpers + +Since 0.4.1 you can express common cadences without writing cron by hand. Each helper is a +thin wrapper over `every(...)`: + +```rust,no_run +# use tasklet::TaskBuilder; +let _ = TaskBuilder::new(chrono::Local).every_seconds(5); // "*/5 * * * * * *" +let _ = TaskBuilder::new(chrono::Local).every_minutes(15); // "0 */15 * * * * *" +let _ = TaskBuilder::new(chrono::Local).every_hours(6); // "0 0 */6 * * * *" +let _ = TaskBuilder::new(chrono::Local).hourly_at(15); // minute 15 of every hour +let _ = TaskBuilder::new(chrono::Local).daily_at(9, 30); // every day at 09:30 +``` + +Out-of-range values (e.g. `every_seconds(60)`) produce an invalid schedule that is +rejected by `build()`, just like an invalid cron string. + +You can also capture the id the scheduler assigns to a task with `add_task_get_id`, which +is handy for addressing an unnamed task through the handle afterwards: + +```rust,no_run +# use tasklet::{TaskBuilder, TaskScheduler}; +# #[tokio::main] +# async fn main() { +let mut scheduler = TaskScheduler::default(chrono::Local); +let id = scheduler + .add_task_get_id(TaskBuilder::new(chrono::Local).every_seconds(5).build()) + .unwrap(); +let handle = scheduler.handle(); +tokio::spawn(async move { handle.trigger(id); }); +# } +``` + ## Naming, runtime control and history Give a task a stable name and address it at runtime through the handle (added in 0.4.0). diff --git a/examples/schedule_helpers_and_streaming.rs b/examples/schedule_helpers_and_streaming.rs new file mode 100644 index 0000000..5c189e0 --- /dev/null +++ b/examples/schedule_helpers_and_streaming.rs @@ -0,0 +1,59 @@ +use log::info; +use simple_logger::SimpleLogger; +use std::time::Duration; +use tasklet::task::TaskStepStatusOk::Success; +use tasklet::{TaskBuilder, TaskScheduler}; + +/// Demonstrates the v0.4.1 additions: +/// +/// * **Schedule helpers**: `every_seconds` builds the cron expression for you. +/// * **`add_task_get_id`**: capture the id of an unnamed task to address it later. +/// * **Live step streaming**: the handle observes step transitions *during* a run, +/// so a completed early step is visible while a later step is still in flight. +#[tokio::main] +async fn main() { + SimpleLogger::new().init().unwrap(); + + let mut scheduler = TaskScheduler::new(200, chrono::Local); + + // A two-step task on a 2-second cadence built without writing raw cron. The + // second step is slow, so its predecessor shows as completed while it runs. + let task = TaskBuilder::new(chrono::Local) + .every_seconds(2) + .add_step("prepare", || async { + info!("step 1: prepare"); + Ok(Success) + }) + .add_step("work (slow)", || async { + info!("step 2: working..."); + tokio::time::sleep(Duration::from_millis(1200)).await; + info!("step 2: done"); + Ok(Success) + }) + .build(); + + // Capture the assigned id so we can address the (unnamed) task through the handle. + let id = scheduler.add_task_get_id(task).unwrap(); + info!("task registered with id {}", id); + + // Poll the per-step snapshot while the task runs to watch it advance live. + let handle = scheduler.handle(); + let observer = tokio::spawn(async move { + for _ in 0..12 { + tokio::time::sleep(Duration::from_millis(500)).await; + let steps: Vec = handle + .step_states(id) + .into_iter() + .map(|s| format!("{}={:?}", s.description.as_deref().unwrap_or("-"), s.status)) + .collect(); + if !steps.is_empty() { + info!("[live steps] {}", steps.join(", ")); + } + } + }); + + scheduler + .run_until(tokio::time::sleep(Duration::from_secs(6))) + .await; + observer.await.unwrap(); +} diff --git a/src/builders.rs b/src/builders.rs index a1dc9e3..646b0f7 100644 --- a/src/builders.rs +++ b/src/builders.rs @@ -176,6 +176,88 @@ where self } + /// Run every `n` seconds. + /// + /// A convenience wrapper over [`every`](Self::every) that builds the equivalent + /// cron expression, so you do not have to write one by hand. `n` must be between 1 + /// and 59; other values produce an invalid schedule that is rejected by + /// [`build`](Self::build). + /// + /// # Examples + /// + /// ```rust + /// # use tasklet::TaskBuilder; + /// let _task = TaskBuilder::new(chrono::Local).every_seconds(5).build().unwrap(); + /// ``` + pub fn every_seconds(self, n: u32) -> TaskBuilder { + self.every(&format!("*/{} * * * * * *", n)) + } + + /// Run every `n` minutes (at second 0). + /// + /// A convenience wrapper over [`every`](Self::every). `n` must be between 1 and 59; + /// other values produce an invalid schedule that is rejected by + /// [`build`](Self::build). + /// + /// # Examples + /// + /// ```rust + /// # use tasklet::TaskBuilder; + /// let _task = TaskBuilder::new(chrono::Local).every_minutes(15).build().unwrap(); + /// ``` + pub fn every_minutes(self, n: u32) -> TaskBuilder { + self.every(&format!("0 */{} * * * * *", n)) + } + + /// Run every `n` hours (at minute 0, second 0). + /// + /// A convenience wrapper over [`every`](Self::every). `n` must be between 1 and 23; + /// other values produce an invalid schedule that is rejected by + /// [`build`](Self::build). + /// + /// # Examples + /// + /// ```rust + /// # use tasklet::TaskBuilder; + /// let _task = TaskBuilder::new(chrono::Local).every_hours(6).build().unwrap(); + /// ``` + pub fn every_hours(self, n: u32) -> TaskBuilder { + self.every(&format!("0 0 */{} * * * *", n)) + } + + /// Run once a day at the given `hour` and `minute` (24-hour clock, second 0). + /// + /// A convenience wrapper over [`every`](Self::every). `hour` must be 0-23 and + /// `minute` 0-59; other values produce an invalid schedule that is rejected by + /// [`build`](Self::build). The time is interpreted in the builder's timezone. + /// + /// # Examples + /// + /// ```rust + /// # use tasklet::TaskBuilder; + /// // Every day at 09:30. + /// let _task = TaskBuilder::new(chrono::Local).daily_at(9, 30).build().unwrap(); + /// ``` + pub fn daily_at(self, hour: u32, minute: u32) -> TaskBuilder { + self.every(&format!("0 {} {} * * * *", minute, hour)) + } + + /// Run once an hour at the given `minute` (second 0). + /// + /// A convenience wrapper over [`every`](Self::every). `minute` must be 0-59; other + /// values produce an invalid schedule that is rejected by [`build`](Self::build). + /// + /// # Examples + /// + /// ```rust + /// # use tasklet::TaskBuilder; + /// // At minute 15 of every hour. + /// let _task = TaskBuilder::new(chrono::Local).hourly_at(15).build().unwrap(); + /// ``` + pub fn hourly_at(self, minute: u32) -> TaskBuilder { + self.every(&format!("0 {} * * * * *", minute)) + } + /// Set the max repeats for the generated `Task`. /// /// # Arguments @@ -600,4 +682,45 @@ mod test { assert_eq!(task.history_limit, DEFAULT_HISTORY_LIMIT); assert!(task.name.is_none()); } + + /// The schedule-helper builders produce valid, buildable cron expressions. (E1) + #[test] + fn test_schedule_helpers_build_valid_expressions() { + let cases = [ + ( + TaskBuilder::new(chrono::Utc).every_seconds(5), + "*/5 * * * * * *", + ), + ( + TaskBuilder::new(chrono::Utc).every_minutes(15), + "0 */15 * * * * *", + ), + ( + TaskBuilder::new(chrono::Utc).every_hours(6), + "0 0 */6 * * * *", + ), + ( + TaskBuilder::new(chrono::Utc).daily_at(9, 30), + "0 30 9 * * * *", + ), + ( + TaskBuilder::new(chrono::Utc).hourly_at(15), + "0 15 * * * * *", + ), + ]; + for (builder, expected) in cases { + assert_eq!(builder.expression, expected); + // The helper parsed the expression eagerly, and it builds. + assert!(builder.schedule.is_some()); + assert!(builder.build().is_ok()); + } + } + + /// A schedule helper given an out-of-range value fails at build time. (E1) + #[test] + fn test_schedule_helper_invalid_value_rejected() { + // Second 60 is out of range, so the generated expression is invalid. + let result = TaskBuilder::new(chrono::Utc).every_seconds(60).build(); + assert!(matches!(result, Err(TaskError::InvalidCronExpression(_)))); + } } diff --git a/src/lib.rs b/src/lib.rs index e32f0bc..94fd8e9 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -21,7 +21,12 @@ //! * **Observability** — query the live task set at runtime through //! [`SchedulerHandle::task_count`] / [`SchedulerHandle::statuses`], including per-task //! run history ([`SchedulerHandle::history`]) and per-step state -//! ([`SchedulerHandle::step_states`]). +//! ([`SchedulerHandle::step_states`]), which streams step transitions live during a run. +//! * **Schedule helpers** — build common cadences without raw cron: +//! [`TaskBuilder::every_seconds`], [`every_minutes`](TaskBuilder::every_minutes), +//! [`every_hours`](TaskBuilder::every_hours), [`hourly_at`](TaskBuilder::hourly_at) and +//! [`daily_at`](TaskBuilder::daily_at). Capture a task's id with +//! [`TaskScheduler::add_task_get_id`]. //! * **Runtime control** — name a task with [`TaskBuilder::name`] and pause, resume, //! trigger or remove it at runtime through a [`SchedulerHandle`], by id or by name. //! * **Shared data** — pass values between tasks and steps with a cheaply-clonable, diff --git a/src/scheduler.rs b/src/scheduler.rs index 1038385..cb84ab9 100644 --- a/src/scheduler.rs +++ b/src/scheduler.rs @@ -422,42 +422,68 @@ where &mut self, task: TaskResult>, ) -> Result<&mut TaskScheduler, TaskError> { - match task { - Ok(mut task) => { - // Enforce name uniqueness so a name is a stable, addressable identity. - if let Some(name) = task.name.as_deref() { - if self.handles.iter().any(|h| h.name.as_deref() == Some(name)) { - return Err(TaskError::DuplicateTaskName(name.to_string())); - } - } + self.add_task_get_id(task)?; + Ok(self) + } - // A buffer of one is enough: the scheduler only dispatches a run when - // the task is idle, so at most one `Run` is ever in flight. - let (sender, receiver) = mpsc::channel(1); - - task.set_receiver(receiver); - task.set_id(self.next_id); - let overlap = task.overlap; - let name = task.name.clone(); - let shared = Arc::new(TaskShared::new(task.history_limit)); - let handle = tokio::spawn(run_task(task, shared.clone())); - - // Push the handle - self.handles.push(TaskHandle { - id: self.next_id, - name, - handle, - sender, - shared, - overlap, - }); - - // Increase the id of the next task. - self.next_id += 1; - Ok(self) + /// Add a new task and return the id the scheduler assigned to it. + /// + /// This is the same as [`add_task`](Self::add_task) except it returns the new + /// task's id instead of `&mut Self`, so callers can address an unnamed task + /// afterwards through a [`SchedulerHandle`] (pause, resume, trigger, remove). + /// + /// If the task has a name (set via [`TaskBuilder::name`](crate::TaskBuilder::name)), + /// it must be unique within the scheduler; a duplicate is rejected with + /// [`TaskError::DuplicateTaskName`]. + /// + /// # Examples + /// + /// ``` + /// # use tasklet::{TaskScheduler, Task}; + /// # tokio_test::block_on( async { + /// let mut scheduler = TaskScheduler::default(chrono::Local); + /// let id = scheduler + /// .add_task_get_id(Task::new("* * * * * * *", None, None, chrono::Local)) + /// .unwrap(); + /// assert_eq!(id, 0); + /// # }); + /// ``` + pub fn add_task_get_id(&mut self, task: TaskResult>) -> Result { + let mut task = task?; + + // Enforce name uniqueness so a name is a stable, addressable identity. + if let Some(name) = task.name.as_deref() { + if self.handles.iter().any(|h| h.name.as_deref() == Some(name)) { + return Err(TaskError::DuplicateTaskName(name.to_string())); } - Err(e) => Err(e), } + + let id = self.next_id; + + // A buffer of one is enough: the scheduler only dispatches a run when + // the task is idle, so at most one `Run` is ever in flight. + let (sender, receiver) = mpsc::channel(1); + + task.set_receiver(receiver); + task.set_id(id); + let overlap = task.overlap; + let name = task.name.clone(); + let shared = Arc::new(TaskShared::new(task.history_limit)); + let handle = tokio::spawn(run_task(task, shared.clone())); + + // Push the handle + self.handles.push(TaskHandle { + id, + name, + handle, + sender, + shared, + overlap, + }); + + // Increase the id of the next task. + self.next_id += 1; + Ok(id) } /// Run a single scheduling round. @@ -1092,6 +1118,40 @@ mod test { assert!(scheduler.add_task(t3).is_ok()); } + /// `add_task_get_id` returns the assigned id and still enforces name uniqueness. (§4.1) + #[tokio::test] + async fn test_add_task_get_id_returns_ids() { + let mut scheduler = TaskScheduler::new(1000, Local); + let id0 = scheduler + .add_task_get_id(Task::new("* * * * * * *", None, None, Local)) + .unwrap(); + let id1 = scheduler + .add_task_get_id(Task::new("* * * * * * *", None, None, Local)) + .unwrap(); + assert_eq!(id0, 0); + assert_eq!(id1, 1); + + // A propagated build error surfaces rather than assigning an id. + assert!(scheduler + .add_task_get_id(Task::new("not a cron", None, None, Local)) + .is_err()); + + // Duplicate names are still rejected. + let named = TaskBuilder::new(Local) + .every("* * * * * * *") + .name("solo") + .build(); + assert_eq!(scheduler.add_task_get_id(named).unwrap(), 2); + let dup = TaskBuilder::new(Local) + .every("* * * * * * *") + .name("solo") + .build(); + assert!(matches!( + scheduler.add_task_get_id(dup), + Err(TaskError::DuplicateTaskName(_)) + )); + } + /// Pausing a task stops its schedule from being dispatched; resuming restores it. (Layer 0) #[tokio::test] async fn test_control_pause_and_resume() { diff --git a/src/task.rs b/src/task.rs index 72b6597..ff8d4eb 100644 --- a/src/task.rs +++ b/src/task.rs @@ -359,6 +359,11 @@ where pub(crate) task_id: usize, /// (Internal) per-step state of the last run, republished after every run. pub(crate) step_states: Vec, + /// (Internal) shared cell to publish step-state transitions to as they happen, so + /// observers see live progress within a run rather than only the final snapshot. + /// Set by the scheduler when the task is spawned; `None` when the task is driven + /// directly (e.g. in unit tests), in which case streaming is a no-op. + pub(crate) step_sink: Option>, /// (Internal) total step attempts made during the last run. pub(crate) last_attempts: usize, /// The maximum number of run records retained for this task. @@ -449,6 +454,7 @@ where timezone, task_id: 0, step_states: Vec::new(), + step_sink: None, last_attempts: 0, history_limit: DEFAULT_HISTORY_LIMIT, status: Status::default(), @@ -583,6 +589,14 @@ where .collect(); } + /// Publish the current per-step snapshot to the shared cell, if a sink is set, so + /// observers see step transitions live during a run. A no-op when no sink is set. + fn publish_steps(&self) { + if let Some(shared) = &self.step_sink { + *shared.steps.lock().unwrap() = self.step_states.clone(); + } + } + /// Set the callbacks invoked over the task's lifecycle. pub(crate) fn set_callbacks( &mut self, @@ -713,12 +727,19 @@ where // Rebuild the per-step snapshot for this run and reset the attempt count. self.reset_step_states(); self.last_attempts = 0; + // Stream the fresh (all-pending) snapshot so observers see the run begin. + self.publish_steps(); let mut had_error: bool = false; - for (index, step) in self.steps.iter_mut().enumerate() { + // Iterate by index so `self` is free between step invocations, letting us + // stream each transition to the shared cell as it happens. + for index in 0..self.steps.len() { if had_error { break; } + // The description is fixed per step; capture it for logging so we do + // not hold a borrow of `self.steps` across the awaited step future. + let step_desc = self.steps[index].to_string(); // Attempt the step, retrying transient (`Error`) failures and // timeouts according to the retry policy. `ErrorDelete` and // success both terminate the attempt loop immediately. @@ -728,10 +749,15 @@ where self.last_attempts += 1; // Run the step, optionally bounded by the configured timeout. - // A timeout is treated as a (retryable) `Error`. + // A timeout is treated as a (retryable) `Error`. Producing the + // step future borrows `self.steps[index]` only until it returns; + // the boxed future is `'static`, so no borrow is held across the + // await and `self` is free afterwards. let result = match timeout { Some(duration) => { - match tokio::time::timeout(duration, (step.function)()).await { + match tokio::time::timeout(duration, (self.steps[index].function)()) + .await + { Ok(result) => result, Err(_) => { step_log!( @@ -740,13 +766,13 @@ where log::Level::Warn, "Timed out after {:?} - {}", duration, - step + step_desc ); Err(TaskStepStatusErr::Error) } } } - None => (step.function)().await, + None => (self.steps[index].function)().await, }; match result { @@ -758,7 +784,7 @@ where index, log::Level::Debug, "Executed successfully - {}", - step + step_desc ); self.step_states[index].status = StepStatus::Succeeded; } @@ -768,12 +794,13 @@ where index, log::Level::Debug, "Executed with non-fatal errors - {}", - step + step_desc ); self.step_states[index].status = StepStatus::HadErrors; } } self.status = Status::Executed; + self.publish_steps(); break; } Err(TaskStepStatusErr::ErrorDelete) => { @@ -782,10 +809,11 @@ where index, log::Level::Error, "Execution failed and task is marked for deletion - {}", - step + step_desc ); self.step_states[index].status = StepStatus::Failed; self.status = Status::ForceRemoved; + self.publish_steps(); had_error = true; break; } @@ -802,7 +830,7 @@ where attempt, max_attempts, delay, - step + step_desc ); if !delay.is_zero() { tokio::time::sleep(delay).await; @@ -814,10 +842,11 @@ where index, log::Level::Error, "Execution failed - {}", - step + step_desc ); self.step_states[index].status = StepStatus::Failed; self.status = Status::Failed; + self.publish_steps(); had_error = true; break; } @@ -830,6 +859,8 @@ where step_state.status = StepStatus::Skipped; } } + // Stream the final per-step outcome (including any skipped steps). + self.publish_steps(); // Avoid underflow in case of a task without steps. if self.steps.is_empty() { self.status = Status::Executed @@ -944,7 +975,9 @@ where T: TimeZone + Send + 'static, ::Offset: Send, { - // Self-initialize and publish the first scheduled time. + // Wire the shared cell as the step-state sink so step transitions stream live + // during each run, then self-initialize and publish the first scheduled time. + task.step_sink = Some(shared.clone()); task.init(); publish(&task, &shared); if task.is_terminal() { @@ -1705,6 +1738,57 @@ mod test { assert_eq!(shared.runs.load(Ordering::SeqCst), 1); } + /// Step-state transitions are streamed to the shared cell during a run, so an + /// observer sees a completed step while a later step is still pending. (§4.3) + #[tokio::test] + async fn test_step_states_stream_live() { + use tokio::sync::Notify; + + let ready = Arc::new(Notify::new()); + let proceed = Arc::new(Notify::new()); + + let (tx, rx) = mpsc::channel(1); + let mut task = Task::new("* * * * * * *", None, Some(1), Utc).unwrap(); + task.set_id(0); + // Step 0 succeeds immediately. + task.add_step("first", || async { Ok(Success) }); + // Step 1 signals that it has been reached, then waits for permission to finish. + let r = ready.clone(); + let p = proceed.clone(); + task.add_step("second", move || { + let r = r.clone(); + let p = p.clone(); + async move { + r.notify_one(); + p.notified().await; + Ok(Success) + } + }); + task.set_receiver(rx); + + let shared = Arc::new(TaskShared::new(DEFAULT_HISTORY_LIMIT)); + let join = tokio::spawn(run_task(task, shared.clone())); + + // Dispatch a run and wait until step 1 is mid-flight. + tx.send(TaskCmd::Run).await.unwrap(); + ready.notified().await; + + // Live snapshot: step 0 already succeeded while step 1 is still pending. + { + let steps = shared.steps.lock().unwrap(); + assert_eq!(steps[0].status, StepStatus::Succeeded); + assert_eq!(steps[1].status, StepStatus::Pending); + } + + // Let step 1 finish; the run completes and, with repeat(1), the task retires. + proceed.notify_one(); + join.await.unwrap(); + + let steps = shared.steps.lock().unwrap(); + assert_eq!(steps[0].status, StepStatus::Succeeded); + assert_eq!(steps[1].status, StepStatus::Succeeded); + } + /// The observable state types round-trip through serde. (Layer 0, `serde` feature) #[cfg(feature = "serde")] #[test]