4.5 时间管理

📚 本节导读

学习时长: 约 120 分钟（含所有子节）
难度级别: ⭐⭐⭐☆☆
前置知识: 实时操作系统基本概念、C 语言指针与回调函数、中断处理基础

🎯 学习目标

• 理解 OneOS 中系统时钟（SysTick）的工作原理
• 掌握哈希桶定时器和单链表定时器两种定时器实现方案的区别与适用场景
• 熟悉定时器相关 API 的使用方法
• 了解时间管理模块的配置选项

一、模块机制全景

时间管理是 OneOS 内核的基础组件，为整个系统提供统一的时间基准和定时/延时功能。其模块机制分类如下：

                          时间管理模块全景
                                 │
        ┌────────────────────────┼────────────────────────┐
        │                        │                        │
   系统时钟(SysTick)        定时器(Timer)             延时服务
        │                        │                        │
   ┌────┴─────┐          ┌───────┴───────┐          ┌─────┴──────┐
   │tick 中断  │          │ 哈希桶定时器    │          │ os_task_    │
   │频率配置   │          │ 单链表定时器    │          │ tsleep/     │
   │tick 队列  │          │  硬/软定时器    │          │ msleep      │
   └──────────┘          └───────────────┘          └────────────┘
        │                        │                        │
   驱动整个系统时序        基于系统时钟的软件/        任务阻塞延时
   （任务延时、时间片）      硬件定时功能              精确计时

• 系统时钟（SysTick）：系统的"心跳"，通过硬件定时器产生周期性中断，驱动任务延时、定时器计时和时间片轮转。
• 定时器（Timer）：基于系统时钟的定时功能，支持哈希桶和单链表两种实现，单次/周期、硬/软两种模式。
• 延时服务：为任务提供精确延时阻塞（os_task_tsleep / os_task_msleep）。

所有时间管理相关 API 在 kernel/include/os_timer.h 中声明，系统时钟实现在 kernel/source/os_clock.c 中。

二、核心机制对比

OneOS 提供哈希桶定时器和单链表定时器两种实现方案，核心差异如下：

特性维度	哈希桶定时器	单链表定时器
插入时间复杂度	O(1)	O(n)
定时器数量	适合大量定时器	适合少量定时器
硬件定时器支持	不支持	支持（ISR 上下文回调）
软件定时器支持	支持	支持（定时器任务回调）
排序方式	哈希桶分散存储	按剩余时间升序链表
内存开销	桶数组 + 链表	单链表
适用场景	大量定时器、插入频繁	少量定时器、需硬件定时器
配置宏	OS_USING_HASH_TIMER	OS_USING_SINGLE_LIST_TIMER

2.1 哈希桶定时器

哈希桶定时器将定时器按超时时间的哈希值分布到不同的桶中，每个桶维护一个定时器链表。插入操作只需计算哈希值并插入对应桶，时间复杂度为 O(1)，非常适合定时器数量较多的场景（详见 4.5.2）。

2.2 单链表定时器

单链表定时器将所有定时器维护在一个按剩余时间排序的链表中。每次插入都需要遍历链表找到合适的位置，时间复杂度为 O(n)。单链表定时器额外支持硬件定时器（在 ISR 上下文中执行回调）和软件定时器（在定时器任务上下文中执行回调）（详见 4.5.3）。

三、选型指南

3.1 何时使用哈希桶定时器

• 定时器数量多（成百上千），需要 O(1) 插入。
• 定时器插入/删除频繁，追求确定性性能。
• 只需软件定时器（回调在定时器任务上下文），无需硬件定时器。
• 典型场景：大量连接的超时管理、网络协议栈定时器。

3.2 何时使用单链表定时器

• 定时器数量少（几十个以内）。
• 需要硬件定时器支持（回调在 ISR 上下文，响应更及时）。
• 定时器数量不是瓶颈，能接受 O(n) 插入。
• 典型场景：需要极低延迟回调、硬件外设定时。

选型快速决策流程：

你的需求是什么？
  │
  ├─ 需要硬件定时器（ISR 上下文回调）？
  │    └─ 是 → 单链表定时器（OS_USING_SINGLE_LIST_TIMER）
  │
  ├─ 定时器数量多 / 插入频繁？
  │    ├─ 是 → 哈希桶定时器（OS_USING_HASH_TIMER）
  │    └─ 否 → 两者皆可；默认选哈希桶（O(1) 更优）
  │
  └─ 追求回调响应及时性？
       ├─ 是 → 单链表定时器（硬定时器）
       └─ 否 → 哈希桶定时器

一句话速记表：

场景	首选机制
大量定时器、O(1) 插入	哈希桶
需硬件定时器（ISR 回调）	单链表
少量定时器	两者皆可（默认哈希桶）
低延迟回调	单链表（硬定时器）

四、模块共性概念

以下概念是 4.5.1~4.5.4 各子章节共享的基础，在此统一归纳，避免各子节重复讲解。

4.1 系统时钟（SysTick）

系统时钟是 OneOS 的心脏，通过硬件定时器（通常为 Cortex-M 的 SysTick）产生固定频率的时钟中断。每个时钟中断称为一个"系统节拍（tick）"，系统节拍频率由 OS_TICK_PER_SECOND 配置。

系统时钟驱动以下核心功能：

• 任务延时：os_task_tsleep(tick) 和 os_task_msleep(ms) 基于系统时钟实现任务阻塞延时
• 定时器计时：所有软件定时器的计时基于系统时钟
• 时间片轮转：同优先级任务的时间片由系统时钟驱动
• Tick 队列：内核维护一个 tick 队列，用于管理所有延时阻塞的任务

4.2 定时器类型

OneOS 定时器支持以下两种工作模式：

模式	标志	说明
单次触发	OS_TIMER_FLAG_ONE_SHOT	定时器到期后只执行一次回调，然后自动停止
周期性触发	OS_TIMER_FLAG_PERIODIC	定时器到期后执行回调并自动重新启动，循环往复

对于单链表定时器，还额外支持以下分类：

类型	标志	说明
硬件定时器	OS_TIMER_FLAG_HARD_TIMER	回调在 tick ISR 中执行，要求回调函数极短且不能阻塞
软件定时器	OS_TIMER_FLAG_SOFT_TIMER	回调在定时器任务上下文中执行，可以执行较复杂操作

4.3 配置选项

时间管理相关的配置宏定义在 oneos_config.h 中：

#define OS_TICK_PER_SECOND         100    /* 系统节拍频率，每秒 tick 数 */
#define OS_USING_KERNEL_TIMER              /* 启用内核定时器功能 */
#define OS_USING_HASH_TIMER                /* 启用哈希桶定时器（二选一） */
// #define OS_USING_SINGLE_LIST_TIMER       /* 启用单链表定时器（二选一） */
// #define OS_HARD_SINGLE_LIST_TIMER        /* 启用硬件单链表定时器 */
// #define OS_SOFT_SINGLE_LIST_TIMER        /* 启用软件单链表定时器 */

注意：OS_USING_HASH_TIMER 和 OS_USING_SINGLE_LIST_TIMER 互斥，只能二选一。OS_HARD_SINGLE_LIST_TIMER 和 OS_SOFT_SINGLE_LIST_TIMER 可以同时启用。

五、子章节导航

子节	标题	内容
4.5.1	系统时钟	SysTick 概念、tick 中断处理、频率配置、tick 队列
4.5.2	哈希桶定时器	O(1) 插入、哈希桶原理、内部数据结构、适用场景
4.5.3	单链表定时器	排序链表、硬/软定时器、周期性补偿、与哈希桶对比
4.5.4	定时器 API	统一 API 手册：签名/参数/返回值/代码示例/跨实现差异（实现源码见 4.5.2/4.5.3）

📝 本节小结

核心要点回顾

• 时间管理是 OneOS 的基础组件，为系统提供统一时间基准和定时/延时功能。
• 模块机制：系统时钟（SysTick，驱动时序）+ 定时器（哈希桶/单链表）+ 延时服务（os_task_tsleep/msleep）。
• 两种定时器：哈希桶（O(1) 插入，适合大量定时器，仅软件）、单链表（O(n) 插入，支持硬/软定时器）。
• 定时器类型：单次/周期触发；硬定时器（ISR 回调）与软定时器（任务回调）。
• 共性概念：系统时钟、定时器类型标志、配置宏（OS_TICK_PER_SECOND、OS_USING_HASH_TIMER/OS_USING_SINGLE_LIST_TIMER）。

关键易错点速查表

易错点	说明	对应章节
定时器方案互斥	OS_USING_HASH_TIMER 与 OS_USING_SINGLE_LIST_TIMER 只能二选一	4.3
哈希桶不支持硬定时器	需 ISR 回调必须用单链表	2.1/3.1
硬定时器回调要短	ISR 上下文回调不能阻塞、要极短	4.2
单链表插入 O(n)	大量定时器时性能下降	2.2
硬/软单链表可并存	OS_HARD_SINGLE_LIST_TIMER 与 OS_SOFT_SINGLE_LIST_TIMER 可同时启用	4.3

下一步

• 4.5.1 系统时钟：了解 SysTick 概念、tick 中断处理与 tick 队列机制。