kestrel-timer 0.4.1

use crate::error::TimerError;
use std::collections::VecDeque;
use std::future::Future;
use std::num::{NonZeroU64, NonZeroUsize};
use std::pin::Pin;
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use tokio::time::Instant;

use deferred_map::{DefaultKey, Key};
use lite_sync::oneshot::lite::{Receiver, Sender, State, channel};
use parking_lot::Mutex;
use tokio::sync::watch;
use tokio::sync::{Notify, mpsc};

/// One-shot task completion state constants
///
/// 一次性任务完成状态常量
const ONESHOT_PENDING: u8 = 0;
const ONESHOT_CALLED: u8 = 1;
const ONESHOT_CANCELLED: u8 = 2;
const ONESHOT_CLOSED: u8 = 3;
const ONESHOT_RECEIVER_CLOSED: u8 = 4;

/// Task Completion Reason for Periodic Tasks
///
/// Indicates the reason for task completion, called or cancelled.
///
/// 任务完成原因，调用或取消。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TaskCompletion {
    /// Task was called
    ///
    /// 任务被调用
    Called,
    /// Task was cancelled
    ///
    /// 任务被取消
    Cancelled,
}

impl State for TaskCompletion {
    #[inline]
    fn to_u8(&self) -> u8 {
        match self {
            TaskCompletion::Called => ONESHOT_CALLED,
            TaskCompletion::Cancelled => ONESHOT_CANCELLED,
        }
    }

    #[inline]
    fn from_u8(value: u8) -> Option<Self> {
        match value {
            ONESHOT_CALLED => Some(TaskCompletion::Called),
            ONESHOT_CANCELLED => Some(TaskCompletion::Cancelled),
            _ => None,
        }
    }

    #[inline]
    fn pending_value() -> u8 {
        ONESHOT_PENDING
    }

    #[inline]
    fn closed_value() -> u8 {
        ONESHOT_CLOSED
    }

    #[inline]
    fn receiver_closed_value() -> u8 {
        ONESHOT_RECEIVER_CLOSED
    }
}

/// Globally unique identity for a timing wheel instance.
///
/// The value is private so callers cannot manufacture an owner identity for a
/// different wheel. It is kept separate from DeferredMap's debug-only map ID,
/// which is not available in release builds.
///
/// 时间轮实例的全局唯一身份。
///
/// 该值保持私有，因此调用者无法伪造另一个时间轮的 owner。它独立于
/// DeferredMap 仅在 debug 构建中提供的 map ID。
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub(crate) struct WheelId(NonZeroU64);

static NEXT_WHEEL_ID: AtomicU64 = AtomicU64::new(1);

impl WheelId {
    #[inline]
    pub(crate) fn new() -> Self {
        let value = NEXT_WHEEL_ID
            .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |current| {
                current.checked_add(1)
            })
            .expect("timing wheel owner ID space exhausted");

        Self(NonZeroU64::new(value).expect("timing wheel owner ID must be non-zero"))
    }
}

/// Shared owner state for a timing wheel.
///
/// Besides identifying the wheel, this state receives unconsumed deferred-map
/// handles. The wheel drains that queue before allocating another handle, so a
/// failed cross-wheel registration does not permanently reserve a slot.
///
/// 时间轮共享 owner 状态。
///
/// 除了标识时间轮，该状态还接收未消费的 deferred-map handle。时间轮会在
/// 再次分配 handle 前清空队列，因此跨轮注册失败不会永久占用槽位。
pub(crate) struct WheelOwner {
    id: WheelId,
    released_handles: Mutex<Vec<deferred_map::Handle>>,
    closed: AtomicBool,
    close_signal: watch::Sender<bool>,
}

impl WheelOwner {
    #[inline]
    pub(crate) fn new() -> Arc<Self> {
        let (close_signal, _) = watch::channel(false);
        Arc::new(Self {
            id: WheelId::new(),
            released_handles: Mutex::new(Vec::new()),
            closed: AtomicBool::new(false),
            close_signal,
        })
    }

    #[inline]
    pub(crate) fn id(&self) -> WheelId {
        self.id
    }

    #[inline]
    fn release_handle(&self, handle: deferred_map::Handle) {
        self.released_handles.lock().push(handle);
    }

    #[inline]
    pub(crate) fn take_released_handles(&self) -> Vec<deferred_map::Handle> {
        std::mem::take(&mut *self.released_handles.lock())
    }

    #[inline]
    pub(crate) fn close(&self) {
        self.closed.store(true, Ordering::Release);
        let _ = self.close_signal.send(true);
    }

    #[inline]
    pub(crate) fn is_closed(&self) -> bool {
        self.closed.load(Ordering::Acquire)
    }

    #[inline]
    pub(crate) fn subscribe_closed(&self) -> watch::Receiver<bool> {
        self.close_signal.subscribe()
    }
}

/// Unique identifier for timer tasks.
///
/// A task ID includes the owning timing wheel identity in addition to the
/// generational DeferredMap key. The owner field is private and is checked by
/// every wheel map operation before the raw key reaches DeferredMap.
///
/// 定时器任务唯一标识符。
///
/// 任务 ID 除了包含 DeferredMap 的代数 key，还包含所属时间轮身份。owner
/// 字段保持私有，所有时间轮 map 操作都会在使用 raw key 前先校验它。
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct TaskId {
    wheel_id: WheelId,
    key: DefaultKey,
}

impl TaskId {
    /// Create TaskId from DeferredMap key (internal use)
    ///
    /// 从 DeferredMap key 创建 TaskId (内部使用)
    #[inline]
    pub(crate) fn from_key(wheel_id: WheelId, key: DefaultKey) -> Self {
        Self { wheel_id, key }
    }

    /// Get the DeferredMap key
    ///
    /// 获取 DeferredMap key
    #[inline]
    pub(crate) fn key(&self) -> DefaultKey {
        self.key
    }

    /// Check whether this ID belongs to the specified timing wheel.
    ///
    /// 检查该 ID 是否属于指定时间轮。
    #[inline]
    pub(crate) fn belongs_to(&self, wheel_id: WheelId) -> bool {
        self.wheel_id == wheel_id
    }

    #[cfg(test)]
    #[inline]
    pub(crate) fn wheel_id(&self) -> WheelId {
        self.wheel_id
    }

    /// Get the numeric value of the task ID
    ///
    /// 获取任务 ID 的数值
    #[inline]
    pub fn raw(&self) -> u64 {
        self.key.raw()
    }
}

pub struct TaskHandle {
    owner: Arc<WheelOwner>,
    handle: Option<deferred_map::Handle>,
}

impl TaskHandle {
    /// Create a new task handle
    ///
    /// 创建一个新的任务句柄
    #[inline]
    pub(crate) fn new(owner: Arc<WheelOwner>, handle: deferred_map::Handle) -> Self {
        Self {
            owner,
            handle: Some(handle),
        }
    }

    /// Get the task ID
    ///
    /// 获取任务 ID
    #[inline]
    pub fn task_id(&self) -> TaskId {
        let handle = self
            .handle
            .as_ref()
            .expect("task handle has already been consumed");
        TaskId::from_key(self.owner.id(), handle.key())
    }

    /// Check whether this handle belongs to the specified timing wheel.
    ///
    /// 检查该 handle 是否属于指定时间轮。
    #[inline]
    pub(crate) fn belongs_to(&self, wheel_id: WheelId) -> bool {
        self.owner.id() == wheel_id
    }

    /// Convert to deferred map handle
    ///
    /// 转换为 deferred map 句柄
    #[inline]
    pub(crate) fn into_handle(mut self) -> deferred_map::Handle {
        self.handle
            .take()
            .expect("task handle has already been consumed")
    }
}

impl Drop for TaskHandle {
    fn drop(&mut self) {
        if let Some(handle) = self.handle.take() {
            self.owner.release_handle(handle);
        }
    }
}

/// Timer Callback Trait
///
/// Types implementing this trait can be used as timer callbacks.
///
/// 可实现此特性的类型可以作为定时器回调函数。
///
/// # Examples (示例)
///
/// ```
/// use kestrel_timer::task::TimerCallback;
/// use std::future::Future;
/// use std::pin::Pin;
///
/// struct MyCallback;
///
/// impl TimerCallback for MyCallback {
///     fn call(&self) -> Pin<Box<dyn Future<Output = ()> + Send>> {
///         Box::pin(async {
///             println!("Timer callback executed!");
///         })
///     }
/// }
/// ```
pub trait TimerCallback: Send + Sync + 'static {
    /// Execute callback, returns a Future
    ///
    /// 执行回调函数，返回一个 Future
    fn call(&self) -> Pin<Box<dyn Future<Output = ()> + Send>>;
}

/// Implement TimerCallback trait for closures
///
/// Supports Fn() -> Future closures, can be called multiple times, suitable for periodic tasks
///
/// 实现 TimerCallback 特性的类型，支持 Fn() -> Future 闭包，可以多次调用，适合周期性任务
impl<F, Fut> TimerCallback for F
where
    F: Fn() -> Fut + Send + Sync + 'static,
    Fut: Future<Output = ()> + Send + 'static,
{
    fn call(&self) -> Pin<Box<dyn Future<Output = ()> + Send>> {
        Box::pin(self())
    }
}

/// Callback wrapper for standardized callback creation and management
///
/// Callback 包装器，用于标准化回调创建和管理
///
/// # Examples (示例)
///
/// ```
/// use kestrel_timer::CallbackWrapper;
///
/// let callback = CallbackWrapper::new(|| async {
///     println!("Timer callback executed!");
/// });
/// ```
#[derive(Clone)]
pub struct CallbackWrapper {
    callback: Arc<dyn TimerCallback>,
}

impl CallbackWrapper {
    /// Create a new callback wrapper
    ///
    /// # Parameters
    /// - `callback`: Callback object implementing TimerCallback trait
    ///
    /// # 创建一个新的回调包装器
    ///
    /// # 参数
    /// - `callback`: 实现 TimerCallback 特性的回调对象
    ///
    /// # Examples (示例)
    ///
    /// ```
    /// use kestrel_timer::CallbackWrapper;
    ///
    /// let callback = CallbackWrapper::new(|| async {
    ///     println!("Timer fired!"); // 定时器触发
    /// });
    /// ```
    #[inline]
    pub fn new(callback: impl TimerCallback) -> Self {
        Self {
            callback: Arc::new(callback),
        }
    }

    /// Call the callback function
    ///
    /// 调用回调函数
    #[inline]
    pub(crate) fn call(&self) -> Pin<Box<dyn Future<Output = ()> + Send>> {
        self.callback.call()
    }
}

/// Task type enum to distinguish between one-shot and periodic timers
///
/// 任务类型枚举，用于区分一次性和周期性定时器
#[derive(Clone)]
pub enum TaskType {
    /// One-shot timer: executes once and completes
    ///
    /// 一次性定时器：执行一次后完成
    OneShot,

    /// Periodic timer: repeats at fixed intervals
    ///
    /// 周期性定时器：按固定间隔重复执行
    Periodic {
        /// Period interval for periodic tasks
        ///
        /// 周期任务的间隔时间
        interval: std::time::Duration,
        /// Maximum number of pending Called notifications; None is unbounded
        ///
        /// 待消费 Called 通知的最大数量；None 表示无界
        buffer_size: Option<NonZeroUsize>,
    },
}

/// Task type enum to distinguish between one-shot and periodic timers
///
/// 任务类型枚举，用于区分一次性和周期性定时器
pub enum TaskTypeWithCompletionNotifier {
    /// One-shot timer: executes once and completes
    ///
    /// 一次性定时器：执行一次后完成
    OneShot {
        completion_notifier: Sender<TaskCompletion>,
    },

    /// Periodic timer: repeats at fixed intervals
    ///
    /// 周期性定时器：按固定间隔重复执行
    Periodic {
        /// Period interval for periodic tasks
        ///
        /// 周期任务的间隔时间
        interval: std::time::Duration,
        /// Completion notifier for periodic tasks
        ///
        /// 周期性任务完成通知器
        completion_notifier: PeriodicCompletionNotifier,
    },
}

impl TaskTypeWithCompletionNotifier {
    /// Get the interval for periodic tasks
    ///
    /// Returns `None` for one-shot tasks
    ///
    /// 获取周期任务的间隔时间
    ///
    /// 对于一次性任务返回 `None`
    #[inline]
    pub fn get_interval(&self) -> Option<std::time::Duration> {
        match self {
            TaskTypeWithCompletionNotifier::Periodic { interval, .. } => Some(*interval),
            TaskTypeWithCompletionNotifier::OneShot { .. } => None,
        }
    }
}

pub(crate) struct PeriodicCompletionQueue {
    state: Mutex<PeriodicCompletionQueueState>,
    notify: Notify,
}

struct PeriodicCompletionQueueState {
    events: VecDeque<TaskCompletion>,
    capacity: Option<NonZeroUsize>,
    terminal_pending: bool,
    closed: bool,
    receiver_alive: bool,
    dropped_called: usize,
}

enum PeriodicReceiveState {
    Empty,
    Closed,
}

impl PeriodicCompletionQueue {
    fn new(capacity: Option<NonZeroUsize>) -> Arc<Self> {
        Arc::new(Self {
            state: Mutex::new(PeriodicCompletionQueueState {
                events: VecDeque::new(),
                capacity,
                terminal_pending: false,
                closed: false,
                receiver_alive: true,
                dropped_called: 0,
            }),
            notify: Notify::new(),
        })
    }

    fn send(&self, completion: TaskCompletion) -> bool {
        let mut state = self.state.lock();
        if state.closed || !state.receiver_alive {
            return false;
        }

        if completion == TaskCompletion::Cancelled {
            state.terminal_pending = true;
            drop(state);
            self.notify.notify_waiters();
            return true;
        }

        if state.terminal_pending {
            return false;
        }

        if let Some(capacity) = state.capacity
            && state.events.len() >= capacity.get()
        {
            state.dropped_called = state.dropped_called.saturating_add(1);
            return false;
        }

        state.events.push_back(completion);
        drop(state);
        self.notify.notify_one();
        true
    }

    fn try_receive(&self) -> Result<TaskCompletion, PeriodicReceiveState> {
        let mut state = self.state.lock();
        if let Some(completion) = state.events.pop_front() {
            return Ok(completion);
        }

        if state.terminal_pending {
            state.terminal_pending = false;
            return Ok(TaskCompletion::Cancelled);
        }

        if state.closed {
            Err(PeriodicReceiveState::Closed)
        } else {
            Err(PeriodicReceiveState::Empty)
        }
    }

    fn close_sender(&self) {
        let mut state = self.state.lock();
        state.closed = true;
        drop(state);
        self.notify.notify_waiters();
    }

    fn close_receiver(&self) {
        let mut state = self.state.lock();
        state.receiver_alive = false;
        state.closed = true;
        state.events.clear();
        state.terminal_pending = false;
        drop(state);
        self.notify.notify_waiters();
    }

    fn dropped_called(&self) -> usize {
        self.state.lock().dropped_called
    }
}

/// Completion notifier for periodic tasks.
///
/// `Some(buffer_size)` keeps at most that many pending `Called` notifications.
/// `None` keeps every notification. A final `Cancelled` notification is kept
/// separately and is never evicted by the bounded queue.
///
/// 周期任务完成通知器。
///
/// `Some(buffer_size)` 最多保留指定数量的待消费 `Called` 通知；`None` 保留
/// 所有通知。最终的 `Cancelled` 通知独立保存，不会被有界队列挤出。
pub struct PeriodicCompletionNotifier(pub(crate) Arc<PeriodicCompletionQueue>);

impl PeriodicCompletionNotifier {
    #[inline]
    pub(crate) fn send(&self, completion: TaskCompletion) -> bool {
        self.0.send(completion)
    }
}

impl Drop for PeriodicCompletionNotifier {
    fn drop(&mut self) {
        self.0.close_sender();
    }
}

/// Completion receiver for periodic tasks
///
/// 周期任务完成通知接收器
pub struct PeriodicCompletionReceiver(pub(crate) Arc<PeriodicCompletionQueue>);

impl PeriodicCompletionReceiver {
    /// Try to receive a completion notification
    ///
    /// 尝试接收完成通知
    #[inline]
    pub fn try_recv(&mut self) -> Result<TaskCompletion, mpsc::error::TryRecvError> {
        match self.0.try_receive() {
            Ok(completion) => Ok(completion),
            Err(PeriodicReceiveState::Empty) => Err(mpsc::error::TryRecvError::Empty),
            Err(PeriodicReceiveState::Closed) => Err(mpsc::error::TryRecvError::Disconnected),
        }
    }

    /// Receive a completion notification
    ///
    /// 接收完成通知
    #[inline]
    pub async fn recv(&mut self) -> Option<TaskCompletion> {
        loop {
            let notified = self.0.notify.notified();
            match self.0.try_receive() {
                Ok(completion) => return Some(completion),
                Err(PeriodicReceiveState::Closed) => return None,
                Err(PeriodicReceiveState::Empty) => notified.await,
            }
        }
    }

    /// Get the number of `Called` notifications discarded by a bounded queue.
    ///
    /// 获取有界队列丢弃的 `Called` 通知数量。
    #[inline]
    pub fn dropped_notifications(&self) -> usize {
        self.0.dropped_called()
    }
}

impl Drop for PeriodicCompletionReceiver {
    fn drop(&mut self) {
        self.0.close_receiver();
    }
}

/// Completion notifier for one-shot tasks
///
/// 一次性任务完成通知器
pub enum CompletionNotifier {
    OneShot(Sender<TaskCompletion>),
    Periodic(PeriodicCompletionNotifier),
}

/// Completion receiver for one-shot and periodic tasks
///
/// 一次性和周期任务完成通知接收器
pub enum CompletionReceiver {
    OneShot(Receiver<TaskCompletion>),
    Periodic(PeriodicCompletionReceiver),
}

/// Timer Task
///
/// Users interact via a two-step API
/// 1. Create task using `TimerTask::new_oneshot()` or `TimerTask::new_periodic()`
/// 2. Register task using `TimerWheel::register()` or `TimerService::register()`
///
/// TaskId is assigned when the task is inserted into the timing wheel.
///
/// 定时器任务
///
/// 用户通过两步 API 与定时器交互
/// 1. 使用 `TimerTask::new_oneshot()` 或 `TimerTask::new_periodic()` 创建任务
/// 2. 使用 `TimerWheel::register()` 或 `TimerService::register()` 注册任务
///
/// TaskId 在任务插入到时间轮时分配
pub struct TimerTask {
    /// Task type (one-shot or periodic)
    ///
    /// 任务类型（一次性或周期性）
    pub(crate) task_type: TaskType,

    /// User-specified delay duration (initial delay for periodic tasks)
    ///
    /// 用户指定的延迟时间（周期任务的初始延迟）
    pub(crate) delay: std::time::Duration,

    /// Async callback function, optional
    ///
    /// 异步回调函数，可选
    pub(crate) callback: Option<CallbackWrapper>,
}

impl TimerTask {
    /// Create a new one-shot timer task
    ///
    /// # Parameters
    /// - `delay`: Delay duration before task execution
    /// - `callback`: Callback function, optional
    ///
    /// # Note
    /// TaskId will be assigned when the task is inserted into the timing wheel.
    /// 创建一个新的一次性定时器任务
    ///
    /// # 参数
    /// - `delay`: 任务执行前的延迟时间
    /// - `callback`: 回调函数，可选
    ///
    /// # 注意
    /// TaskId 将在任务插入到时间轮时分配
    #[inline]
    pub fn new_oneshot(delay: std::time::Duration, callback: Option<CallbackWrapper>) -> Self {
        Self {
            task_type: TaskType::OneShot,
            delay,
            callback,
        }
    }

    /// Create a new periodic timer task
    ///
    /// # Parameters
    /// - `initial_delay`: Initial delay before first execution
    /// - `interval`: Interval between subsequent executions
    /// - `callback`: Callback function, optional
    /// - `buffer_size`: Maximum pending `Called` notifications; `None` is
    ///   unbounded
    ///
    /// # Note
    /// TaskId will be assigned when the task is inserted into the timing wheel.
    /// The interval must be greater than zero. The timing wheel also requires it
    /// to be at least the configured L0 tick duration.
    ///
    /// Returns `Err(TimerError::InvalidConfiguration)` for a zero interval.
    ///
    /// 创建一个新的周期性定时器任务
    ///
    /// # 参数
    /// - `initial_delay`: 首次执行前的初始延迟
    /// - `interval`: 后续执行之间的间隔
    /// - `callback`: 回调函数，可选
    /// - `buffer_size`: 待消费 `Called` 通知的最大数量；`None` 表示无界
    ///
    /// # 注意
    /// TaskId 将在任务插入到时间轮时分配。
    /// 有界模式超出的 `Called` 通知可通过 `PeriodicCompletionReceiver::dropped_notifications`
    /// 查询。
    #[inline]
    pub fn new_periodic(
        initial_delay: std::time::Duration,
        interval: std::time::Duration,
        callback: Option<CallbackWrapper>,
        buffer_size: Option<NonZeroUsize>,
    ) -> Result<Self, TimerError> {
        if interval.is_zero() {
            return Err(TimerError::InvalidConfiguration {
                field: "interval".to_string(),
                reason: "periodic interval must be greater than zero".to_string(),
            });
        }

        Ok(Self {
            task_type: TaskType::Periodic {
                interval,
                buffer_size,
            },
            delay: initial_delay,
            callback,
        })
    }

    /// Get task type
    ///
    /// 获取任务类型
    #[inline]
    pub fn get_task_type(&self) -> &TaskType {
        &self.task_type
    }

    /// Get the interval for periodic tasks
    ///
    /// Returns `None` for one-shot tasks
    ///
    /// 获取周期任务的间隔时间
    ///
    /// 对于一次性任务返回 `None`
    #[inline]
    pub fn get_interval(&self) -> Option<std::time::Duration> {
        match self.task_type {
            TaskType::Periodic { interval, .. } => Some(interval),
            TaskType::OneShot => None,
        }
    }
}

/// Timer Task
///
/// Users interact via a two-step API
/// 1. Create task using `TimerTask::new_oneshot()` or `TimerTask::new_periodic()`
/// 2. Register task using `TimerWheel::register()` or `TimerService::register()`
///
/// 定时器任务
///
/// 用户通过两步 API 与定时器交互
/// 1. 使用 `TimerTask::new_oneshot()` 或 `TimerTask::new_periodic()` 创建任务
/// 2. 使用 `TimerWheel::register()` 或 `TimerService::register()` 注册任务
pub struct TimerTaskWithCompletionNotifier {
    /// Task type (one-shot or periodic)
    ///
    /// 任务类型（一次性或周期性）
    pub(crate) task_type: TaskTypeWithCompletionNotifier,

    /// User-specified delay duration (initial delay for periodic tasks)
    ///
    /// 用户指定的延迟时间（周期任务的初始延迟）
    pub(crate) delay: std::time::Duration,

    /// Async callback function, optional
    ///
    /// 异步回调函数，可选
    pub(crate) callback: Option<CallbackWrapper>,
}

impl TimerTaskWithCompletionNotifier {
    /// Create a new timer task with completion notifier from a timer task
    ///
    /// TaskId will be assigned later when inserted into the timing wheel
    ///
    /// 从定时器任务创建一个新的定时器任务完成通知器
    ///
    /// TaskId 将在插入到时间轮时分配
    ///
    /// # Parameters
    /// - `task`: The timer task to create from
    ///
    /// # Returns
    /// A tuple containing the new timer task with completion notifier and the completion receiver
    ///
    /// 返回一个包含新的定时器任务完成通知器和完成通知接收器的元组
    ///
    pub fn from_timer_task(task: TimerTask) -> (Self, CompletionReceiver) {
        match task.task_type {
            TaskType::OneShot => {
                // Create oneshot notifier and receiver with optimized single Arc allocation
                // 创建 oneshot 通知器和接收器，使用优化的单个 Arc 分配
                let (notifier, receiver) = channel();

                (
                    Self {
                        task_type: TaskTypeWithCompletionNotifier::OneShot {
                            completion_notifier: notifier,
                        },
                        delay: task.delay,
                        callback: task.callback,
                    },
                    CompletionReceiver::OneShot(receiver),
                )
            }
            TaskType::Periodic {
                interval,
                buffer_size,
            } => {
                let queue = PeriodicCompletionQueue::new(buffer_size);

                let notifier = PeriodicCompletionNotifier(Arc::clone(&queue));
                let receiver = PeriodicCompletionReceiver(queue);

                (
                    Self {
                        task_type: TaskTypeWithCompletionNotifier::Periodic {
                            interval,
                            completion_notifier: notifier,
                        },
                        delay: task.delay,
                        callback: task.callback,
                    },
                    CompletionReceiver::Periodic(receiver),
                )
            }
        }
    }

    /// Into task type
    ///
    /// 将任务类型转换为完成通知器
    #[inline]
    pub fn into_task_type(self) -> TaskTypeWithCompletionNotifier {
        self.task_type
    }

    /// Get the interval for periodic tasks
    ///
    /// Returns `None` for one-shot tasks
    ///
    /// 获取周期任务的间隔时间
    ///
    /// 对于一次性任务返回 `None`
    #[inline]
    pub fn get_interval(&self) -> Option<std::time::Duration> {
        self.task_type.get_interval()
    }
}

pub(crate) struct TimerTaskForWheel {
    pub(crate) task_id: TaskId,
    pub(crate) task: TimerTaskWithCompletionNotifier,
    pub(crate) deadline_tick: u64,
    pub(crate) rounds: u32,
    pub(crate) deadline_at: Instant,
}

impl TimerTaskForWheel {
    /// Create a new timer task for wheel with assigned TaskId
    ///
    /// 使用分配的 TaskId 创建一个新的定时器任务用于时间轮
    ///
    /// # Parameters
    /// - `task_id`: The TaskId assigned by DeferredMap
    /// - `task`: The timer task to create from
    /// - `deadline_tick`: The deadline tick for the task
    /// - `rounds`: The rounds for the task
    ///
    /// # Returns
    /// A new timer task for wheel
    ///
    /// 返回一个新的定时器任务用于时间轮
    ///
    #[inline]
    pub(crate) fn new_with_id(
        task_id: TaskId,
        task: TimerTaskWithCompletionNotifier,
        deadline_tick: u64,
        rounds: u32,
        deadline_at: Instant,
    ) -> Self {
        Self {
            task_id,
            task,
            deadline_tick,
            rounds,
            deadline_at,
        }
    }

    /// Get task ID
    ///
    /// 获取任务 ID
    #[inline]
    pub fn get_id(&self) -> TaskId {
        self.task_id
    }

    /// Into task type
    ///
    /// 将任务类型转换为完成通知器
    #[inline]
    pub fn into_task_type(self) -> TaskTypeWithCompletionNotifier {
        self.task.into_task_type()
    }

    /// Update the delay of the timer task
    ///
    /// 更新定时器任务的延迟
    ///
    /// # Parameters
    /// - `delay`: The new delay for the task
    ///
    #[inline]
    pub fn update_delay(&mut self, delay: std::time::Duration) {
        self.task.delay = delay
    }

    /// Update the callback of the timer task
    ///
    /// 更新定时器任务的回调
    ///
    /// # Parameters
    /// - `callback`: The new callback for the task
    ///
    #[inline]
    pub fn update_callback(&mut self, callback: CallbackWrapper) {
        self.task.callback = Some(callback)
    }
}

/// Task location information (including level) for hierarchical timing wheel
///
/// Memory layout optimization: level field placed first to reduce padding via struct alignment
///
/// 任务位置信息（包括层级）用于分层时间轮
///
/// 内存布局优化：将 level 字段放在第一位，通过结构体对齐来减少填充
#[derive(Debug, Clone, Copy)]
pub(crate) struct TaskLocation {
    /// Slot index
    ///
    /// 槽索引
    pub slot_index: usize,
    /// Index position of task in slot Vec for O(1) cancellation
    ///
    /// 槽向量中任务的索引位置，用于 O(1) 取消
    pub vec_index: usize,
    /// Level: 0 = L0 (bottom layer), 1 = L1 (upper layer)
    /// Using u8 instead of bool to reserve space for potential multi-layer expansion
    ///
    /// 层级：0 = L0（底层），1 = L1（上层）
    /// 使用 u8 而不是 bool 来保留空间，用于潜在的多层扩展
    pub level: u8,
}

impl TaskLocation {
    /// Create a new task location information
    ///
    /// 创建一个新的任务位置信息
    #[inline(always)]
    pub fn new(level: u8, slot_index: usize, vec_index: usize) -> Self {
        Self {
            slot_index,
            vec_index,
            level,
        }
    }
}