footing 0.4.4

Feature-gated foundations for Rust backend services
Documentation
use std::{sync::Arc, time::Duration};

use tokio::sync::Notify;

/// Scheduling intent after a successful worker tick.
///
/// A tick has exactly one intent. Setting a schedule replaces the previous intent.
/// Both [`super::WorkerTick`] and [`super::BatchRunSummary`] use this type.
/// Worker-level errors always use failure backoff instead. Shutdown takes
/// precedence over every schedule, and each new tick still checks its lease.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
#[non_exhaustive]
pub enum WorkerSchedule {
    /// Wait for the configured polling interval, ignoring wakeup notifications.
    #[default]
    Poll,
    /// Check for more immediately executable work after the minimum queue interval.
    ///
    /// This is a hint, not a guarantee of work. The runtime never infers it from
    /// the number of processed, failed, skipped, or retrying items.
    Continue,
    /// Wait for this duration, ignoring wakeup notifications.
    ///
    /// Zero requests an immediate next tick. The minimum queue interval does
    /// not apply to an explicit delay. An unrepresentable timer deadline stops
    /// the runner with [`super::WorkerRunError::DelayOutOfRange`].
    After(Duration),
    /// Wait for a notification or a bounded polling check, whichever comes first.
    ///
    /// Works without a wakeup handle and when producers stop notifying. Queue
    /// schedules respect [`super::WorkerConfig::min_queue_interval`]. The store
    /// must still enforce task due times; a wakeup only requests another check.
    WaitForWork {
        /// Optional earlier check, measured from the end of the tick.
        ///
        /// The wait is capped by `poll_interval`. This is a best-effort hint,
        /// not a prohibition on checking sooner or a task execution deadline.
        recheck_after: Option<Duration>,
    },
}

/// Coalescing wakeup signal for one worker runner.
///
/// Clone the handle for producers and install it with
/// [`super::WorkerRunOptions::with_wakeup`]. Notify **after** the enqueue
/// transaction commits. External listeners can forward events through the same
/// handle; the worker has no dependency on their transport or database.
///
/// Notifications carry no tasks and are not counted: at most one pending signal
/// is retained, including a signal sent before the worker starts waiting. A
/// notification during a tick can cause one extra queue check. Use a separate
/// handle for each runner; clones share a signal, they do not broadcast it.
/// Dropping producer handles leaves polling operational.
///
/// Only [`WorkerSchedule::WaitForWork`] consumes signals. Notifications never
/// interrupt startup delays, explicit delays, failure backoff, or lease waits.
#[derive(Debug, Clone, Default)]
pub struct WorkerWakeup {
    notify: Arc<Notify>,
}

impl WorkerWakeup {
    /// Creates an independent wakeup signal.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Requests a queue check without blocking the producer.
    pub fn notify(&self) {
        self.notify.notify_one();
    }

    pub(super) async fn wait(&self) {
        self.notify.notified().await;
    }
}