Struct ScheduledTask 

pub struct ScheduledTask {

    pub name: String,
    pub schedule: Schedule,
    pub args: Vec<Value>,
    pub kwargs: HashMap<String, Value>,
    pub options: TaskOptions,
    pub last_run_at: Option<DateTime<Utc>>,
    pub total_run_count: u64,
    pub enabled: bool,
    pub jitter: Option<Jitter>,
    pub catchup_policy: CatchupPolicy,
    pub group: Option<String>,
    pub tags: HashSet<String>,
    pub retry_policy: RetryPolicy,
    pub retry_count: u32,
    pub last_failure_at: Option<DateTime<Utc>>,
    pub total_failure_count: u64,
    pub execution_history: Vec<ExecutionRecord>,
    pub max_history_size: usize,
    pub version_history: Vec<ScheduleVersion>,
    pub current_version: u32,
    pub dependencies: HashSet<String>,
    pub wait_for_dependencies: bool,
    pub alert_config: AlertConfig,
    pub execution_state: ExecutionState,
    pub wfq_state: Option<WFQState>,
    /* private fields */
}

Scheduled task

Fields

name: String

Task name

schedule: Schedule

Task schedule

args: Vec<Value>

Task arguments

kwargs: HashMap<String, Value>

Task keyword arguments

options: TaskOptions

Task options

last_run_at: Option<DateTime<Utc>>

Last run timestamp

total_run_count: u64

Total run count

enabled: bool

Enabled flag

jitter: Option<Jitter>

Jitter configuration

catchup_policy: CatchupPolicy

Catch-up policy for missed schedules

group: Option<String>

Task group (for organizational purposes)

tags: HashSet<String>

Task tags (for filtering and categorization)

retry_policy: RetryPolicy

Retry policy for failed executions

retry_count: u32

Current retry attempt count

last_failure_at: Option<DateTime<Utc>>

Last failure timestamp

total_failure_count: u64

Total failure count

execution_history: Vec<ExecutionRecord>

Execution history (last N executions)

max_history_size: usize

Maximum number of history records to keep (0 = unlimited)

version_history: Vec<ScheduleVersion>

Version history (tracks schedule modifications)

current_version: u32

Current version number

dependencies: HashSet<String>

Task dependencies (task names this task depends on)

wait_for_dependencies: bool

Whether to wait for all dependencies before running

alert_config: AlertConfig

Alert configuration for this task

execution_state: ExecutionState

Current execution state (for crash recovery)

wfq_state: Option<WFQState>

Weighted Fair Queuing state

Implementations

impl ScheduledTask

pub fn with_jitter_window(self, window_secs: u64) -> Self

Add bounded, deterministic jitter to this entry’s next-run time.

This is a convenience over ScheduledTask::with_jitter that configures a symmetric ±window_secs window. The resulting offset is derived from a stable hash of the entry name and the target fire time (see bounded_jitter_offset) and is applied additively wherever the next run is computed (ScheduledTask::next_run_time, ScheduledTask::is_due, and the running beat loop).

A window_secs of 0 is a no-op: the next-run time is unchanged, so callers can configure jitter unconditionally without altering opted-out behaviour.

Examples

use celers_beat::{Schedule, ScheduledTask};

let task = ScheduledTask::new("report".to_string(), Schedule::interval(60))
    .with_jitter_window(30);
assert!(task.jitter.is_some());

impl ScheduledTask

pub fn new(name: String, schedule: Schedule) -> Self

pub fn with_args(self, args: Vec<Value>) -> Self

pub fn with_kwargs(self, kwargs: HashMap<String, Value>) -> Self

pub fn disabled(self) -> Self

pub fn with_queue(self, queue: String) -> Self

pub fn with_priority(self, priority: u8) -> Self

pub fn with_expires(self, expires: u64) -> Self

pub fn with_jitter(self, jitter: Jitter) -> Self

Add jitter to avoid thundering herd

pub fn with_catchup_policy(self, policy: CatchupPolicy) -> Self

Set catch-up policy for missed schedules

pub fn with_retry_policy(self, policy: RetryPolicy) -> Self

Set retry policy for failed executions

pub fn with_group(self, group: String) -> Self

Set task group

pub fn with_tag(self, tag: String) -> Self

Add a single tag

pub fn with_tags(self, tags: HashSet<String>) -> Self

Add multiple tags

pub fn with_alert_config(self, config: AlertConfig) -> Self

Set alert configuration

pub fn add_tag(&mut self, tag: String)

Add a tag to existing tags

pub fn remove_tag(&mut self, tag: &str) -> bool

Remove a tag

pub fn has_tag(&self, tag: &str) -> bool

Check if task has a specific tag

pub fn is_in_group(&self, group: &str) -> bool

Check if task is in a specific group

pub fn is_due(&self) -> Result<bool, ScheduleError>

Check if task is due to run

pub fn next_run_time(&self) -> Result<DateTime<Utc>, ScheduleError>

Get the next scheduled run time (with jitter if configured)

pub fn update_next_run_cache(&mut self)

Calculate and cache the next run time

This method calculates the next run time and caches it for future calls. The cache is invalidated when the schedule changes or the task is executed.

pub fn invalidate_next_run_cache(&mut self)

Invalidate the next run time cache

This should be called whenever the schedule changes or the task is executed.

pub fn is_enabled(&self) -> bool

Check if task is enabled

pub fn has_run(&self) -> bool

Check if task has run at least once

pub fn has_options(&self) -> bool

Check if task has custom options

pub fn age_since_last_run(&self) -> Option<Duration>

Get age since last run (if task has run)

pub fn mark_success(&mut self)

Mark task execution as successful

pub fn mark_failure(&mut self)

Mark task execution as failed

pub fn should_retry(&self) -> bool

Check if task should be retried

pub fn begin_execution(&mut self, timeout_seconds: Option<u64>)

Begin task execution (for crash recovery tracking)

Marks the task as running and records the start time. This allows detection of interrupted executions after a crash.

Arguments

• timeout_seconds - Optional timeout in seconds for execution detection

pub fn complete_execution(&mut self)

Complete task execution (for crash recovery tracking)

Marks the task as idle and records the execution result. This should be called after every execution (success, failure, or timeout).

pub fn detect_interrupted_execution(&self) -> bool

Detect if this task has an interrupted execution

Returns true if the task is marked as running but should have completed based on timeout or time elapsed.

Returns

• true if execution appears to be interrupted
• false if execution is idle or still valid

pub fn recover_from_interruption(&mut self) -> Option<Duration>

Recover from interrupted execution

Handles cleanup and recording of an interrupted execution. Creates an execution record marked as Interrupted and resets state.

Returns

Duration the task was running before interruption

pub fn is_ready_for_retry_after_crash(&self) -> bool

Check if task is ready for retry after interruption

pub fn next_retry_delay(&self) -> Option<u64>

Get next retry delay in seconds

pub fn next_retry_time(&self) -> Option<DateTime<Utc>>

Calculate next retry time based on last failure

pub fn is_ready_for_retry(&self) -> bool

Check if task is ready for retry

pub fn failure_rate(&self) -> f64

Get failure rate (0.0 to 1.0)

pub fn with_max_history(self, max_size: usize) -> Self

Set maximum history size

pub fn add_execution_record(&mut self, record: ExecutionRecord)

Add execution record to history

pub fn get_last_executions(&self, n: usize) -> &[ExecutionRecord]

Get last N execution records

pub fn get_all_executions(&self) -> &[ExecutionRecord]

Get all execution records

pub fn history_success_count(&self) -> usize

Get success count from history

pub fn history_failure_count(&self) -> usize

Get failure count from history

pub fn consecutive_failure_count(&self) -> u32

Get consecutive failure count from the end of history

Returns the number of consecutive failures at the end of the execution history. If the last execution was successful or if there’s no history, returns 0.

pub fn history_timeout_count(&self) -> usize

Get timeout count from history

pub fn average_duration_ms(&self) -> Option<u64>

Get average execution duration (in milliseconds)

pub fn min_duration_ms(&self) -> Option<u64>

Get minimum execution duration (in milliseconds)

pub fn max_duration_ms(&self) -> Option<u64>

Get maximum execution duration (in milliseconds)

pub fn history_success_rate(&self) -> f64

Get recent success rate from history (0.0 to 1.0)

pub fn clear_history(&mut self)

Clear execution history

pub fn check_health(&self) -> HealthCheckResult

Perform health check on this task

pub fn is_stuck(&self) -> Option<Duration>

Check if task is stuck (hasn’t executed in a long time despite being enabled) Returns Some(duration) if stuck, None otherwise

pub fn validate_schedule(&self) -> Result<(), ScheduleError>

Validate schedule syntax and configuration

pub fn update_schedule( &mut self, new_schedule: Schedule, change_reason: Option<String>, )

Update schedule and create a new version

pub fn update_config( &mut self, enabled: Option<bool>, jitter: Option<Option<Jitter>>, catchup_policy: Option<CatchupPolicy>, change_reason: Option<String>, )

Update schedule configuration (enabled, jitter, catchup) and create a new version

pub fn rollback_to_version( &mut self, version_number: u32, ) -> Result<(), ScheduleError>

Rollback to a previous version

pub fn get_version_history(&self) -> &[ScheduleVersion]

Get all versions in chronological order

pub fn get_version(&self, version_number: u32) -> Option<&ScheduleVersion>

Get a specific version

pub fn get_previous_version(&self) -> Option<&ScheduleVersion>

Get the latest version before current

pub fn add_dependency(&mut self, task_name: String)

Add a dependency (task that must complete before this task)

pub fn remove_dependency(&mut self, task_name: &str) -> bool

Remove a dependency

pub fn clear_dependencies(&mut self)

Clear all dependencies

pub fn has_dependencies(&self) -> bool

Check if task has any dependencies

pub fn depends_on(&self, task_name: &str) -> bool

Check if task depends on a specific task

pub fn with_dependencies(self, dependencies: HashSet<String>) -> Self

Set multiple dependencies at once

pub fn with_wait_for_dependencies(self, wait: bool) -> Self

Set whether to wait for dependencies

pub fn check_dependencies( &self, completed_tasks: &HashSet<String>, ) -> DependencyStatus

Check dependency status against completed tasks

pub fn check_dependencies_with_failures( &self, completed_tasks: &HashSet<String>, failed_tasks: &HashSet<String>, ) -> DependencyStatus

Check dependency status with failed tasks tracking

impl ScheduledTask

pub fn with_business_calendar(self, _calendar: BusinessCalendar) -> Self

Set business calendar for this task

This doesn’t currently enforce business hours (requires more extensive changes), but provides the configuration for future use.

pub fn with_holiday_calendar(self, _calendar: HolidayCalendar) -> Self

Set holiday calendar for this task

This doesn’t currently enforce holidays (requires more extensive changes), but provides the configuration for future use.

impl ScheduledTask

pub fn with_wfq_weight(self, weight: f64) -> Result<Self, String>

Set WFQ weight for this task

Example

use celers_beat::{ScheduledTask, Schedule};

let task = ScheduledTask::new("important_task".to_string(), Schedule::interval(60))
    .with_wfq_weight(5.0).unwrap();

pub fn wfq_weight(&self) -> f64

Get WFQ weight for this task

pub fn wfq_finish_time(&self) -> f64

Get WFQ virtual finish time

Trait Implementations

impl Clone for ScheduledTask

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ScheduledTask

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ScheduledTask

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for ScheduledTask

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Serialize for ScheduledTask

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.