ax-task 0.8.2

use alloc::sync::Arc;
use core::num::NonZeroU64;

use crate::{
    runtime::{
        TaskSystem,
        context::{
            RuntimeIrqGuard, RuntimeSchedulerFrameGuard, runtime_current_cpu_mut,
            runtime_task_system,
        },
        cpu::CpuLocal,
        lock::PreemptScope,
        service::SchedulerTickMode,
        switch::{RuntimeScheduleOrigin, RuntimeSchedulerEntry, dispatch::execute_switch_plan},
        task_runtime,
    },
    sched::{
        CpuId, SchedulePolicy,
        system::{DeadlineBaseGuardSource, SchedulerDeadlineDerivationSource},
    },
    thread::{
        ParkCommit, ParkPrepare, TaskError, ThreadCore, ThreadId, ThreadWakeHandle,
        current::{BlockingPermit, acquire_blocking_permit, current_thread_core_arc},
    },
    time::{MonotonicDeadline, MonotonicInstant, queue::TaskDeadlineKind},
};

/// Result of beginning an externally queued current-thread park transaction.
///
/// OS wait subsystems use this after validating their condition under their own
/// queue lock. The scheduler still owns the generation, deadline, and context
/// switch transaction; callers own only publication and removal of their
/// domain-specific waiter record.
#[derive(Debug)]
pub enum CurrentParkStart {
    /// A preceding wake was consumed, so no waiter may be published for this attempt.
    Notified,
    /// The current thread entered `Parking` and must be committed or cancelled.
    Prepared(PreparedCurrentPark),
}

/// Move-only ownership of one prepared current-thread park transaction.
#[must_use = "a prepared current-thread park must be committed or cancelled"]
#[derive(Debug)]
pub struct PreparedCurrentPark {
    thread: Arc<ThreadCore>,
    ticket: Option<crate::thread::ParkTicket>,
    // Reuse the validated runtime owner through schedule-out. Looking it up
    // again at commit repeats registry and handle checks on the futex hot path.
    system: &'static TaskSystem,
}

/// Terminal scheduler information returned after a prepared park resumes.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct CurrentParkResume {
    generation: u64,
    deadline_expired: bool,
    disposition: CurrentParkDisposition,
}

/// Scheduler disposition of one completed current-thread park transaction.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum CurrentParkDisposition {
    /// A scheduler notification cancelled the park before schedule-out.
    NotifiedBeforeBlock,
    /// The current thread committed `Blocked`, switched out, and later resumed.
    BlockedAndResumed,
}

impl CurrentParkResume {
    /// Returns the scheduler park generation completed by this transaction.
    pub const fn generation(self) -> u64 {
        self.generation
    }

    /// Reports whether an armed task deadline physically expired before cleanup.
    pub const fn deadline_expired(self) -> bool {
        self.deadline_expired
    }

    /// Returns whether this park switched out or was cancelled before blocking.
    pub const fn disposition(self) -> CurrentParkDisposition {
        self.disposition
    }

    /// Reports whether a scheduler notification cancelled schedule-out.
    pub const fn was_notified_before_block(self) -> bool {
        matches!(
            self.disposition,
            CurrentParkDisposition::NotifiedBeforeBlock
        )
    }
}

impl PreparedCurrentPark {
    /// Returns the generation-bearing scheduler identity being parked.
    pub fn thread_id(&self) -> ThreadId {
        self.thread.id()
    }

    /// Returns a generation-bearing wake capability for this parked thread.
    ///
    /// External waiter queues should publish only this restricted capability,
    /// not a full scheduler thread handle.
    pub fn wake_handle(&self) -> ThreadWakeHandle {
        ThreadWakeHandle::from_core(Arc::clone(&self.thread))
    }

    /// Returns this park attempt's monotonically increasing generation.
    pub fn generation(&self) -> u64 {
        self.ticket()
            .expect("prepared park ticket remains owned")
            .generation()
    }

    /// Arms an absolute deadline in the runtime's finite monotonic domain.
    pub fn arm_deadline(&mut self, deadline: MonotonicDeadline) -> Result<(), TaskError> {
        let ticket = self
            .ticket
            .as_mut()
            .expect("prepared park ticket remains owned");
        arm_current_park_deadline(&self.thread, ticket, deadline)
    }

    /// Commits the scheduler park and returns after this thread is runnable again.
    pub fn commit(mut self) -> Result<CurrentParkResume, TaskError> {
        let mut ticket = self
            .ticket
            .take()
            .expect("prepared park ticket remains owned");
        let generation = ticket.generation();
        let deadline_armed = ticket.has_deadline();
        let disposition =
            match commit_current_park_with_system(self.system, &self.thread, &mut ticket) {
                Ok(disposition) => disposition,
                Err(error) => {
                    let deadline_result = cancel_current_park_deadline(&self.thread, &mut ticket);
                    if cancel_current_park(&self.thread, &mut ticket).is_err() {
                        task_runtime::fatal_invariant(
                            0x5041_0002,
                            self.thread.id().as_u64() as usize,
                        );
                    }
                    let _cancelled = deadline_result?;
                    return Err(error);
                }
            };
        let deadline_cancelled = cancel_current_park_deadline(&self.thread, &mut ticket)?;
        Ok(CurrentParkResume {
            generation,
            deadline_expired: deadline_armed && !deadline_cancelled,
            disposition,
        })
    }

    /// Cancels this transaction without blocking the current thread.
    pub fn cancel(mut self) -> Result<(), TaskError> {
        let mut ticket = self
            .ticket
            .take()
            .expect("prepared park ticket remains owned");
        let deadline_result = cancel_current_park_deadline(&self.thread, &mut ticket);
        let park_result = cancel_current_park(&self.thread, &mut ticket);
        let _cancelled = deadline_result?;
        park_result
    }

    fn ticket(&self) -> Option<&crate::thread::ParkTicket> {
        self.ticket.as_ref()
    }
}

impl Drop for PreparedCurrentPark {
    fn drop(&mut self) {
        if self
            .ticket
            .as_ref()
            .is_some_and(|ticket| !ticket.is_resolved())
        {
            task_runtime::fatal_invariant(0x5041_0003, self.thread.id().as_u64() as usize);
        }
    }
}

/// Begins a scheduler-owned park transaction for an OS-owned waiter queue.
///
/// The caller must serialize its condition check and waiter publication so a
/// selecting producer either observes the waiter or leaves the scheduler's
/// sticky wake-before-park notification. This function is bounded and does not
/// sleep, allocate, or invoke OS callbacks.
pub fn begin_current_park() -> Result<CurrentParkStart, TaskError> {
    let permit = acquire_blocking_permit()?;
    begin_current_park_with_permit(&permit)
}

pub(crate) fn begin_current_park_with_permit(
    _permit: &BlockingPermit,
) -> Result<CurrentParkStart, TaskError> {
    let system = runtime_task_system()?;
    // `current` is migration-stable only while task preemption is disabled.
    // Keep this lighter than the CPU/rq owner protocol: the pin exists solely
    // to make the independent task_cpu/on_rq and on_cpu publications one
    // current-task observation before PARKING becomes visible.
    let _current_pin = PreemptScope::enter();
    let thread = current_thread_core_arc()?;
    let prepare = system.prepare_current_park(&thread);
    match prepare? {
        ParkPrepare::Notified => Ok(CurrentParkStart::Notified),
        ParkPrepare::Prepared(ticket) => Ok(CurrentParkStart::Prepared(PreparedCurrentPark {
            thread,
            ticket: Some(ticket),
            system,
        })),
    }
}

/// Performs one bounded task-clockevent pass without allocation or callbacks.
pub fn on_clock_event(
    now: MonotonicInstant,
    budget: usize,
    scheduler_event: ClaimedSchedulerDeadlines,
) -> Result<TaskClockEventOutcome, TaskError> {
    let system = runtime_task_system()?;
    let mut irq = RuntimeIrqGuard::enter();
    let mut cpu = runtime_current_cpu_mut(&mut irq)?;
    let periodic_tick = scheduler_event.runs_periodic_task_tick();
    if periodic_tick && cpu.promote_lazy_reschedule() {
        // Linux PREEMPT_RT promotes TIF_NEED_RESCHED_LAZY before invoking the
        // current class's periodic task_tick hook through resched_curr(). The
        // logical request and architecture preemption word are separate here,
        // so publish both before IRQ return. A new lazy request created by the
        // class hook remains lazy until the following promotion point.
        let _self_serviced = task_runtime::publish_local_scheduler_work();
    }
    // A plain hard-timer callback may enqueue Fair work. Linux settles the
    // current Fair entity before enqueue and wakeup-preemption comparisons;
    // take the owner-rq accounting sample before running callbacks so the
    // same ordering also holds for our shared hard-timer path.
    let (charge, clock, current, task_tick_rq_observation) = match scheduler_event.accounting_kind()
    {
        ClockAccountingKind::RuntimeOnly => {
            system.charge_current_until_with_clock(cpu.as_mut(), 0)?
        }
        ClockAccountingKind::SchedulerDeadline => {
            system.clock_event_current_until_with_clock(cpu.as_mut(), 0)?
        }
        ClockAccountingKind::PeriodicTick => system.task_tick_current_until_with_clock(
            cpu.as_mut(),
            0,
            scheduler_event.periodic_tick_ns(),
        )?,
        ClockAccountingKind::PeriodicTickWithSchedulerDeadline => system
            .task_tick_and_clock_event_current_until_with_clock(
                cpu.as_mut(),
                0,
                scheduler_event.periodic_tick_ns(),
            )?,
    };
    let rt_period_rescheduled = system.service_rt_period(&cpu, now);
    let hard = system.service_due_hard_timers(cpu.as_mut(), now, budget)?;
    let batch = hard.soft();
    let rq_observation =
        match clock_event_rq_observation_plan(rt_period_rescheduled, hard.processed()) {
            ClockEventRqObservationPlan::ReuseAccounted => cpu
                .as_mut()
                .scheduler_work_due_from_rq_observation(now, task_tick_rq_observation),
            ClockEventRqObservationPlan::RefreshAndPublish => cpu.as_mut().scheduler_work_due(now),
        };
    let runtime_deadline = cpu.scheduler_runtime_deadline_for_rq_observation(rq_observation);
    let update = cpu
        .as_mut()
        .next_scheduler_deadline_update_from_rq_observation(
            rq_observation,
            SchedulerDeadlineDerivationSource::ClockEvent,
        )?;
    Ok(TaskClockEventOutcome {
        slice_expired: charge.slice_expired(),
        deadline_overrun: charge.deadline_overrun(),
        expired: hard.processed().saturating_add(batch.expired()),
        update,
        runtime_deadline: Some(runtime_deadline),
        scheduler_tick: SchedulerTickStamp {
            cpu: cpu.owner(),
            thread: current,
            observed_ns: clock.task().as_nanos(),
        },
    })
}

const fn clock_event_rq_observation_reusable(
    rt_period_rescheduled: bool,
    hard_timers_processed: usize,
) -> bool {
    !rt_period_rescheduled && hard_timers_processed == 0
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum ClockEventRqObservationPlan {
    ReuseAccounted,
    RefreshAndPublish,
}

const fn clock_event_rq_observation_plan(
    rt_period_rescheduled: bool,
    hard_timers_processed: usize,
) -> ClockEventRqObservationPlan {
    if clock_event_rq_observation_reusable(rt_period_rescheduled, hard_timers_processed) {
        ClockEventRqObservationPlan::ReuseAccounted
    } else {
        // A hard-timer callback may make the current rq deadline due even
        // when this physical edge did not claim the scheduler runtime timer.
        // Linux's hrtick callback publishes reschedule work before it leaves
        // the hard-timer queue; a fresh observation here must do the same.
        ClockEventRqObservationPlan::RefreshAndPublish
    }
}

/// Scheduler-owned deadlines claimed by one physical clockevent firing.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ClaimedSchedulerDeadlines {
    periodic_tick_ns: Option<NonZeroU64>,
    scheduler_deadline_elapsed: bool,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum ClockAccountingKind {
    RuntimeOnly,
    SchedulerDeadline,
    PeriodicTick,
    PeriodicTickWithSchedulerDeadline,
}

impl ClaimedSchedulerDeadlines {
    /// Captures the periodic-tick duration and independent scheduler deadline
    /// observed by the physical clockevent owner.
    pub const fn new(
        periodic_tick_ns: Option<NonZeroU64>,
        scheduler_deadline_elapsed: bool,
    ) -> Self {
        Self {
            periodic_tick_ns,
            scheduler_deadline_elapsed,
        }
    }

    const fn runs_periodic_task_tick(self) -> bool {
        self.periodic_tick_ns.is_some()
    }

    fn periodic_tick_ns(self) -> u64 {
        match self.periodic_tick_ns {
            Some(tick_ns) => tick_ns.get(),
            None => task_runtime::fatal_invariant(0x5251_1013, 0),
        }
    }

    const fn accounting_kind(self) -> ClockAccountingKind {
        match (
            self.periodic_tick_ns.is_some(),
            self.scheduler_deadline_elapsed,
        ) {
            (false, false) => ClockAccountingKind::RuntimeOnly,
            (false, true) => ClockAccountingKind::SchedulerDeadline,
            (true, false) => ClockAccountingKind::PeriodicTick,
            (true, true) => ClockAccountingKind::PeriodicTickWithSchedulerDeadline,
        }
    }
}

/// Samples CPU time and publishes extension work for a periodic scheduler tick
/// already accounted by [`on_clock_event`].
///
/// The opaque stamp binds this publication to the exact `rq->curr` and task
/// clock sampled by the preceding owner-rq transaction. Physical clockevent
/// sources therefore do not pass compatibility booleans into task deadline
/// processing, and a delayed publication cannot silently target a new task.
pub fn publish_scheduler_tick(
    stamp: SchedulerTickStamp,
    mode: SchedulerTickMode,
    tick_ns: u64,
) -> Result<(), TaskError> {
    if tick_ns == 0 {
        return Err(TaskError::InvalidConfiguration);
    }
    let system = runtime_task_system()?;
    let mut irq = RuntimeIrqGuard::enter();
    let cpu = runtime_current_cpu_mut(&mut irq)?;
    if cpu.owner() != stamp.cpu {
        return Err(TaskError::CpuOwnerMismatch {
            expected: stamp.cpu.as_u32(),
            actual: cpu.owner().as_u32(),
        });
    }
    system.publish_current_scheduler_tick_work(&cpu, stamp.thread, stamp.observed_ns, mode, tick_ns)
}

pub(crate) fn commit_current_park(
    current: &Arc<ThreadCore>,
    ticket: &mut crate::thread::ParkTicket,
) -> Result<CurrentParkDisposition, TaskError> {
    let system = runtime_task_system()?;
    commit_current_park_with_system(system, current, ticket)
}

fn commit_current_park_with_system(
    system: &'static TaskSystem,
    current: &Arc<ThreadCore>,
    ticket: &mut crate::thread::ParkTicket,
) -> Result<CurrentParkDisposition, TaskError> {
    // The task scheduler frame is the authoritative Linux schedule-entry
    // boundary. Its `Task` claim validates IRQ state, hard-IRQ context, and
    // preemption depth while taking the baton; repeating the public blocking
    // probe here would toggle IRQs twice for every park without adding a
    // stronger guarantee.
    let mut scheduler_frame = RuntimeSchedulerFrameGuard::enter(
        RuntimeScheduleOrigin::Block,
        RuntimeSchedulerEntry::Task,
    )?;
    let commit = {
        let mut cpu = runtime_current_cpu_mut(&mut scheduler_frame)?;
        // SAFETY: `scheduler_frame` owns the IRQ-off scheduler baton.
        unsafe { system.commit_park_in_scheduler_frame(cpu.as_mut(), current, ticket)? }
    };
    match commit {
        ParkCommit::Notified => Ok(CurrentParkDisposition::NotifiedBeforeBlock),
        ParkCommit::Blocked(mut decision) => {
            execute_switch_plan(&mut scheduler_frame, &mut decision);
            Ok(CurrentParkDisposition::BlockedAndResumed)
        }
    }
}

pub(crate) fn cancel_current_park(
    current: &ThreadCore,
    ticket: &mut crate::thread::ParkTicket,
) -> Result<(), TaskError> {
    let mut irq = RuntimeIrqGuard::enter();
    let mut cpu = runtime_current_cpu_mut(&mut irq)?;
    runtime_task_system()?.cancel_current_park(cpu.as_mut(), current, ticket)
}

pub(crate) fn arm_current_park_deadline(
    thread: &Arc<ThreadCore>,
    ticket: &mut crate::thread::ParkTicket,
    deadline: MonotonicDeadline,
) -> Result<(), TaskError> {
    let mut irq = RuntimeIrqGuard::enter();
    let cpu = runtime_current_cpu_mut(&mut irq)?;
    if ticket.thread() != thread.id()
        || ticket.is_resolved()
        || ticket.has_deadline()
        || cpu.current() != Some(thread.id())
    {
        return Err(TaskError::StaleThreadId);
    }
    let owner = cpu.owner();
    let (registration, update) = {
        let mut deadline_base = cpu
            .remote()
            .lock_deadline_activity(DeadlineBaseGuardSource::Registration);
        let non_timer = deadline_base.non_timer;
        let kind = TaskDeadlineKind::park_timeout(ticket.generation());
        let registration = if matches!(
            thread.base_policy_snapshot(),
            SchedulePolicy::Fifo { .. }
                | SchedulePolicy::RoundRobin { .. }
                | SchedulePolicy::Deadline(_)
        ) {
            deadline_base.queue.arm_hard_park(
                thread.sleep_timer(),
                deadline,
                kind,
                Arc::clone(thread),
            )
        } else {
            deadline_base
                .queue
                .arm(thread.sleep_timer(), deadline, kind)
        }
        .map_err(|error| match error {
            crate::time::queue::TaskDeadlineError::Capacity => TaskError::TimerCapacity,
            crate::time::queue::TaskDeadlineError::GenerationExhausted
            | crate::time::queue::TaskDeadlineError::KindMismatch => {
                TaskError::InvalidConfiguration
            }
        })?;
        let token = registration.token();
        thread.register_sleep_timer(owner, token.generation());
        let update = match CpuLocal::update_scheduler_deadline_registration_publication(
            &mut deadline_base,
            non_timer,
        ) {
            Ok(update) => update,
            Err(error) => {
                let removed = deadline_base.queue.cancel(&registration);
                let completed = thread.complete_sleep_timer(token.generation());
                if !removed || !completed {
                    task_runtime::fatal_invariant(0x5444_0005, thread.id().as_u64() as usize);
                }
                return Err(error);
            }
        };
        (registration, update)
    };
    task_runtime::publish_scheduler_deadline(update);
    if ticket.attach_deadline(registration).is_err() {
        task_runtime::fatal_invariant(0x5444_0002, thread.id().as_u64() as usize);
    }
    Ok(())
}

pub(crate) fn cancel_current_park_deadline(
    thread: &ThreadCore,
    ticket: &mut crate::thread::ParkTicket,
) -> Result<bool, TaskError> {
    if ticket.thread() != thread.id() {
        return Err(TaskError::StaleThreadId);
    }
    let Some(token) = ticket.deadline().map(|registration| registration.token()) else {
        return Ok(false);
    };
    let system = runtime_task_system()?;
    let mut irq = RuntimeIrqGuard::enter();
    let cpu = runtime_current_cpu_mut(&mut irq)?;
    let actual = cpu.owner();
    let Some(expected) = thread.sleep_timer_cpu_for(token.generation()) else {
        // Expiration physically removes the queue entry and clears the core's
        // matching generation before the owner thread resumes. Only that
        // terminal state permits consuming the ticket without queue access.
        if !ticket.clear_deadline(token) {
            task_runtime::fatal_invariant(0x5444_0003, thread.id().as_u64() as usize);
        }
        return Ok(false);
    };
    if actual != expected {
        let remote = system
            .cpu_remote(expected)
            .ok_or(TaskError::CpuOffline(expected.as_u32()))?;
        let registration = ticket
            .deadline()
            .expect("the deadline registration remains owned until cancellation");
        let (cancellation, expired) = {
            let mut deadline_base =
                remote.lock_deadline_activity(DeadlineBaseGuardSource::Registration);
            let cancellation = deadline_base.queue.begin_cancel(registration);
            let expired = if cancellation.is_none() {
                deadline_base.cancel_expired_task_deadline(registration)
            } else {
                false
            };
            (cancellation, expired)
        };
        let cancelled = match (cancellation, expired) {
            (Some(cancellation), _) => {
                // Linux does not reprogram another CPU's clockevent when a
                // remote hrtimer is removed. The stale edge is conservative;
                // its owner recomputes the authoritative queue when it fires.
                cancellation.commit();
                true
            }
            (None, true) => false,
            (None, false) if thread.sleep_timer_cpu_for(token.generation()).is_none() => {
                if !ticket.clear_deadline(token) {
                    task_runtime::fatal_invariant(0x5444_0003, thread.id().as_u64() as usize);
                }
                return Ok(false);
            }
            (None, false) => {
                task_runtime::fatal_invariant(0x5444_0006, thread.id().as_u64() as usize)
            }
        };
        if !thread.complete_sleep_timer(token.generation()) || !ticket.clear_deadline(token) {
            task_runtime::fatal_invariant(0x5444_0004, thread.id().as_u64() as usize);
        }
        return Ok(cancelled);
    }
    let (cancellation, update) = {
        let registration = ticket
            .deadline()
            .expect("the deadline registration remains owned until cancellation");
        let mut deadline_base = cpu
            .remote()
            .lock_deadline_activity(DeadlineBaseGuardSource::Registration);
        let non_timer = deadline_base.non_timer;
        let cancellation = deadline_base.queue.begin_cancel(registration);
        let expired = if cancellation.is_none() {
            deadline_base.cancel_expired_task_deadline(registration)
        } else {
            false
        };
        let cancellation = match (cancellation, expired) {
            (Some(cancellation), _) => cancellation,
            (None, true) => {
                if !thread.complete_sleep_timer(token.generation()) || !ticket.clear_deadline(token)
                {
                    task_runtime::fatal_invariant(0x5444_0004, thread.id().as_u64() as usize);
                }
                return Ok(false);
            }
            (None, false) if thread.sleep_timer_cpu_for(token.generation()).is_none() => {
                if !ticket.clear_deadline(token) {
                    task_runtime::fatal_invariant(0x5444_0003, thread.id().as_u64() as usize);
                }
                return Ok(false);
            }
            (None, false) => {
                task_runtime::fatal_invariant(0x5444_0006, thread.id().as_u64() as usize);
            }
        };
        let update = match CpuLocal::update_scheduler_deadline_registration_publication(
            &mut deadline_base,
            non_timer,
        ) {
            Ok(update) => update,
            Err(error) => {
                cancellation.rollback(&mut deadline_base.queue);
                return Err(error);
            }
        };
        (cancellation, update)
    };
    task_runtime::publish_scheduler_deadline(update);
    cancellation.commit();
    if !thread.complete_sleep_timer(token.generation()) || !ticket.clear_deadline(token) {
        task_runtime::fatal_invariant(0x5444_0004, thread.id().as_u64() as usize);
    }
    Ok(true)
}

/// Bounded task-clockevent result consumed by the runtime clockevent owner.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct TaskClockEventOutcome {
    slice_expired: bool,
    deadline_overrun: bool,
    expired: usize,
    update: crate::runtime::cpu::SchedulerDeadlineUpdate,
    runtime_deadline: Option<crate::runtime::cpu::SchedulerRuntimeDeadline>,
    scheduler_tick: SchedulerTickStamp,
}

/// Opaque owner-rq sample required to publish one periodic scheduler tick.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct SchedulerTickStamp {
    cpu: CpuId,
    thread: ThreadId,
    observed_ns: u64,
}

impl TaskClockEventOutcome {
    /// Returns whether the current scheduling slice or budget expired.
    pub const fn slice_expired(self) -> bool {
        self.slice_expired
    }
    /// Returns whether the current Deadline reservation exhausted its CBS budget.
    pub const fn deadline_overrun(self) -> bool {
        self.deadline_overrun
    }
    /// Returns the number of timer events claimed by this bounded IRQ pass.
    pub const fn expired(self) -> usize {
        self.expired
    }
    /// Returns the complete generation-ordered task-deadline publication.
    pub const fn update(self) -> crate::runtime::cpu::SchedulerDeadlineUpdate {
        self.update
    }
    /// Returns an owner-local class-runtime update when rq state was sampled.
    pub const fn runtime_deadline(self) -> Option<crate::runtime::cpu::SchedulerRuntimeDeadline> {
        self.runtime_deadline
    }
    /// Returns the rq-bound stamp consumed when this physical edge was also a
    /// periodic scheduler tick.
    pub const fn scheduler_tick_stamp(self) -> SchedulerTickStamp {
        self.scheduler_tick
    }
    /// Returns the next finite task-owned deadline.
    pub const fn next_deadline(self) -> Option<MonotonicDeadline> {
        self.update.deadline()
    }
}

#[cfg(test)]
mod tests {
    use core::num::NonZeroU64;

    use super::{
        ClaimedSchedulerDeadlines, ClockAccountingKind, ClockEventRqObservationPlan,
        clock_event_rq_observation_plan, clock_event_rq_observation_reusable,
    };

    const _: () = assert!(matches!(
        clock_event_rq_observation_plan(false, 1),
        ClockEventRqObservationPlan::RefreshAndPublish
    ));

    #[test]
    fn only_periodic_clock_events_run_the_scheduler_tick() {
        let tick_ns = NonZeroU64::new(10).unwrap();

        assert!(!ClaimedSchedulerDeadlines::new(None, false).runs_periodic_task_tick());
        assert!(!ClaimedSchedulerDeadlines::new(None, true).runs_periodic_task_tick());
        assert!(ClaimedSchedulerDeadlines::new(Some(tick_ns), false).runs_periodic_task_tick());
        assert!(ClaimedSchedulerDeadlines::new(Some(tick_ns), true).runs_periodic_task_tick());
    }

    #[test]
    fn unrelated_physical_clockevent_only_accounts_runtime() {
        let tick_ns = NonZeroU64::new(10).unwrap();

        assert_eq!(
            ClaimedSchedulerDeadlines::new(None, false).accounting_kind(),
            ClockAccountingKind::RuntimeOnly
        );
        assert_eq!(
            ClaimedSchedulerDeadlines::new(None, true).accounting_kind(),
            ClockAccountingKind::SchedulerDeadline
        );
        assert_eq!(
            ClaimedSchedulerDeadlines::new(Some(tick_ns), false).accounting_kind(),
            ClockAccountingKind::PeriodicTick
        );
        assert_eq!(
            ClaimedSchedulerDeadlines::new(Some(tick_ns), true).accounting_kind(),
            ClockAccountingKind::PeriodicTickWithSchedulerDeadline
        );
    }

    #[test]
    fn linux_common_tick_reuses_the_task_tick_rq_observation() {
        assert!(clock_event_rq_observation_reusable(false, 0));
        assert!(!clock_event_rq_observation_reusable(true, 0));
        assert!(!clock_event_rq_observation_reusable(false, 1));
    }

    #[test]
    fn plain_hard_timer_rechecks_and_publishes_due_scheduler_work() {
        assert_eq!(
            clock_event_rq_observation_plan(false, 1),
            ClockEventRqObservationPlan::RefreshAndPublish
        );
    }
}