# Kernel Timer — DragonOS dev 文档

备注

AI Translation Notice

This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.

- Source document: kernel/sched/kernel_timer.md

- Translation time: 2025-05-19 01:41:48

- Translation model: `Qwen/Qwen3-8B`

Please report issues via Community Channel

# Kernel Timer

## 1. Introduction

The kernel timer is a type of timer within the kernel. The working mechanism of the kernel timer is: adding the timer to a queue and setting the expiration time for each timer. When the timer expires, the function corresponding to the timer is executed.

## 2. Design Concept

The timer type is a structure of `Timer`, and `Timer` is composed of `SpinLock<InnerTimer>`. A global queue `TIMER_LIST` with element type `Arc<Timer>` is used to store the timers created by the system. When creating a timer, you should call `Timer::new(timer_func,expire_jiffies)`, where timer_func is the function to be executed by the timer, expire_jiffies is the expiration time of the timer, and the type of `timer_func` parameter is a structure that implements the `TimerFunction` characteristic. After creating the timer, you should use `Timer::activate()` to insert the timer into `TIMER_LIST`.

If you only want the current PCB to sleep for a certain period, you should call `schedule_timeout(timeout)`, and timeout specifies the duration of the PCB sleep.

## 3. Features That the Timer Should Implement

The function to be executed by the timer should implement the `TimerFunction` characteristic, and its definition is as follows:

    /// 定时器要执行的函数的特征
    pub trait TimerFunction: Send + Sync {
        fn run(&mut self);
    }

A typical implementation method is: creating a zero-length structure, implementing the `TimerFunction` characteristic, and then implementing the operation to be performed by the timer in the `run` function.

## 4. Timer API

### 4.1. Timer API

#### 4.1.1. Create a Timer

    pub fn new(timer_func: Box<dyn TimerFunction>, expire_jiffies: u64) -> Arc<Self>

Parameters

- timer_func: A structure corresponding to the function that the timer needs to execute, which implements the `TimerFunction` characteristic

- expire_jiffies: The expiration time of the timer (unit: jiffies)

Return

- Pointer to the timer structure

#### 4.1.2. Insert the Timer into the Timer List

    pub fn activate(&self)

### 4.2. Other APIs

If you want to use the following functions in a .c module, please add rs_ before the function name.

#### 4.2.1. Make the Process Sleep for a Certain Period

    pub fn schedule_timeout(mut timeout: i64) -> Result<i64, SystemError>

Function

Make the process sleep for timeout jiffies

Parameters

- timeout: The time to sleep (unit: jiffies)

Return Value

- Ok(i64): Remaining time to sleep (unit: jiffies)

- Err(SystemError): Error code

#### 4.2.2. Get the Expiration Time of the First Timer in the Queue

    pub fn timer_get_first_expire() -> Result<u64, SystemError>

Function

Get the expiration time of the first timer in the queue, i.e., the expiration time of the earliest expiring timer

Return Value

- Ok(i64): Expiration time of the earliest expiring timer (unit: jiffies)

- Err(SystemError): Error code

#### 4.2.3. Get the Current System Time

    pub fn clock() -> u64

Function

Get the current system time (unit: jiffies)

#### 4.2.4. Calculate the Timer Time Slice Corresponding to the Next n Milliseconds or Microseconds

##### 4.2.4.1. Milliseconds

    pub fn next_n_ms_timer_jiffies(expire_ms: u64) -> u64

Function

Calculate the timer time slice corresponding to the next n milliseconds

Parameters

- expire_ms: n milliseconds

Return Value

The corresponding timer time slice (unit: milliseconds)

##### 4.2.4.2. Microseconds

    pub fn next_n_us_timer_jiffies(expire_us: u64) -> u64

Function

Calculate the timer time slice corresponding to the next n microseconds

Parameters

- expire_ms: n microseconds

Return Value

The corresponding timer time slice (unit: microseconds)

## 5. Creating a Timer Instance

    struct TimerExample {
        /// 结构体的成员对应函数的形参
        example_parameter: i32,
    }
    impl TimerExample {
        pub fn new(para: i32) -> Box<TimerExample> {
            return Box::new(TimerExample {
                example_parameter: para,
            });
        }
    }
    /// 为结构体实现TimerFunction特性
    impl TimerFunction for TimerExample {
        /// TimerFunction特性中的函数run
        fn run(&mut self) {
            // 定时器需要执行的操作
            example_func(self.example_parameter);
        }
    }
    fn example_func(para: i32) {
        println!("para is {:?}", para);
    }
    fn main() {
        let timer_example: Box<TimerExample> = TimerExample::new(1);
        // 创建一个定时器
        let timer: Arc<Timer> = Timer::new(timer_example, 1);
        // 将定时器插入队列
        timer.activate();
    }

Other Versions v: V0.2.0

Tags
  V0.1.0
  V0.1.1
  V0.1.10
  V0.1.2
  V0.1.3
  V0.1.4
  V0.1.5
  V0.1.6
  V0.1.7
  V0.1.8
  V0.1.9
  V0.2.0
  V0.3.0
  V0.4.0

Branches
  master