1# 与“等待”相关的api(C语言)
2
3:::{warning}
4
5随着内核的发展,我们将会逐步将C语言的等待机制替换为Rust语言的等待机制。在这个过程中,我们将会同时保留C语言和Rust语言的等待机制,以便于我们在开发过程中进行对比。
6待时机成熟,我们将会逐步将C语言的等待机制移除。
7:::
8
9  如果几个进程需要等待某个事件发生,才能被运行,那么就需要一种“等待”的机制,以实现进程同步。
10
11## 一. wait_queue等待队列
12
13  wait_queue是一种进程同步机制,中文名为“等待队列”。它可以将当前进程挂起,并在时机成熟时,由另一个进程唤醒他们。
14
15  当您需要等待一个事件完成时,使用wait_queue机制能减少进程同步的开销。相比于滥用自旋锁以及信号量,或者是循环使用usleep(1000)这样的函数来完成同步,wait_queue是一个高效的解决方案。
16
17:::{warning}
18`wait_queue.h`中的等待队列的实现并没有把队列头独立出来,同时没有考虑为等待队列加锁。所以在后来的开发中加入了`wait_queue_head_t`的队列头实现,实质上就是链表+自旋锁。它与`wait_queue.h`中的队列`wait_queue_node_t`是兼容的,当你使用`struct wait_queue_head`作为队列头时,你同样可以使用等待队列添加节点的函数。
19:::
20
21### 简单用法
22
23  等待队列的使用方法主要分为以下几部分:
24
25- 创建并初始化一个等待队列
26- 使用`wait_queue_sleep_on_`系列的函数,将当前进程挂起。晚挂起的进程将排在队列的尾部。
27- 通过`wait_queue_wakeup()`函数,依次唤醒在等待队列上的进程,将其加入调度队列
28
29&emsp;&emsp;要使用wait_queue,您需要`#include<common/wait_queue.h>`,并创建一个`wait_queue_node_t`类型的变量,作为等待队列的头部。这个结构体只包含两个成员变量:
30
31```c
32typedef struct
33{
34    struct List wait_list;
35    struct process_control_block *pcb;
36} wait_queue_node_t;
37```
38
39&emsp;&emsp;对于等待队列,这里有一个好的命名方法:
40
41```c
42wait_queue_node_t wq_keyboard_interrupt_received;
43```
44
45&emsp;&emsp;这样的命名方式能增加代码的可读性,更容易让人明白这里到底在等待什么。
46
47### 初始化等待队列
48
49&emsp;&emsp;函数`wait_queue_init(wait_queue_node_t *wait_queue, struct process_control_block *pcb)`提供了初始化wait_queue结点的功能。
50
51&emsp;&emsp;当您初始化队列头部时,您仅需要将wait_queue首部的结点指针传入,第二个参数请设置为NULL
52
53
54
55### 将结点插入等待队列
56
57&emsp;&emsp;您可以使用以下函数,将当前进程挂起,并插入到指定的等待队列。这些函数大体功能相同,只是在一些细节上有所不同。
58
59| 函数名                                 | 解释                                                          |
60| ----------------------------------- | ----------------------------------------------------------- |
61| wait_queue_sleep_on()               | 将当前进程挂起,并设置挂起状态为PROC_UNINTERRUPTIBLE                        |
62| wait_queue_sleep_on_unlock()        | 将当前进程挂起,并设置挂起状态为PROC_UNINTERRUPTIBLE。待当前进程被插入等待队列后,解锁给定的自旋锁 |
63| wait_queue_sleep_on_interriptible() | 将当前进程挂起,并设置挂起状态为PROC_INTERRUPTIBLE                          |
64
65### 从等待队列唤醒一个进程
66
67&emsp;&emsp;您可以使用`void wait_queue_wakeup(wait_queue_node_t * wait_queue_head, int64_t state);`函数,从指定的等待队列中,唤醒第一个挂起时的状态与指定的`state`相同的进程。
68
69&emsp;&emsp;当没有符合条件的进程时,将不会唤醒任何进程,仿佛无事发生。
70
71
72------------------------------------------------------------
73&emsp;&emsp;
74&emsp;&emsp;
75&emsp;&emsp;
76
77
78## 二. wait_queue_head等待队列头
79
80&emsp;&emsp; 数据结构定义如下:
81
82```c
83typedef struct
84{
85    struct List wait_list;
86    spinlock_t lock;  // 队列需要有一个自旋锁,虽然目前内部并没有使用,但是以后可能会用.
87} wait_queue_head_t;
88```
89
90&emsp;&emsp; 等待队列头的使用逻辑与等待队列实际是一样的,因为他同样也是等待队列的节点(仅仅多了一把锁)。且wait_queue_head的函数基本上与wait_queue一致,只不过多了\*\*\*\_with\_node\_\*\*\*的字符串。
91
92&emsp;&emsp; 同时,wait_queue.h文件中提供了很多的宏,可以方便您的工作。
93
94### 提供的宏
95| 宏                               | 解释                                                          |
96| ----------------------------------- | ----------------------------------------------------------- |
97| DECLARE_WAIT_ON_STACK(name, pcb)             | 在栈上声明一个wait_queue节点,同时把pcb所代表的进程与该节点绑定 |
98| DECLARE_WAIT_ON_STACK_SELF(name)     | 传在栈上声明一个wait_queue节点,同时当前进程(即自身进程)与该节点绑定 |
99| DECLARE_WAIT_ALLOC(name, pcb)  | 使用`kzalloc`声明一个wait_queue节点,同时把pcb所代表的进程与该节点绑定,请记得使用kfree释放空间 |
100| DECLARE_WAIT_ALLOC_SELF(name)      | 使用`kzalloc`声明一个wait_queue节点,同时当前进程(即自身进程)与该节点绑定,请记得使用kfree释放空间 |
101
102
103
104### 创建等待队列头
105&emsp;&emsp; 您可以直接调用宏
106```c
107DECLARE_WAIT_QUEUE_HEAD(m_wait_queue_head);  // 在栈上声明一个队列头变量
108```
109&emsp;&emsp; 也可以手动声明
110```c
111struct wait_queue_head_t m_wait_queue_head = {0};
112wait_queue_head_init(&m_wait_queue_head);
113```
114
115
116### 将结点插入等待队列
117
118| 函数名                                 | 解释                                                          |
119| ----------------------------------- | ----------------------------------------------------------- |
120| wait_queue_sleep_with_node(wait_queue_head_t *head, wait_queue_node_t *wait_node)              | 传入一个等待队列节点,并设置该节点的挂起状态为PROC_UNINTERRUPTIBLE                        |
121| wait_queue_sleep_with_node_unlock(wait_queue_head_t *q, wait_queue_node_t *wait, void *lock)      | 传入一个等待队列节点,将该节点的pcb指向的进程挂起,并设置挂起状态为PROC_UNINTERRUPTIBLE。待当前进程被插入等待队列后,解锁给定的自旋锁 |
122| wait_queue_sleep_with_node_interriptible(wait_queue_head_t *q, wait_queue_node_t *wait) | 传入一个等待队列节点,将该节点的pcb指向的进程挂起,并设置挂起状态为PROC_INTERRUPTIBLE                          |
123
124
125
126### 从等待队列唤醒一个进程
127&emsp;&emsp; 在`wait_queue.h`中的`wait_queue_wakeup`函数直接kfree掉了wait_node节点。对于在栈上的wait_node,您可以选择`wait_queue_wakeup_on_stack(wait_queue_head_t *q, int64_t state)`来唤醒队列里面的队列头节点。
128
129------------------------------------------------------------
130&emsp;&emsp;
131&emsp;&emsp;
132&emsp;&emsp;
133
134## 三. completion完成量
135
136
137### 简单用法
138&emsp;&emsp;完成量的使用方法主要分为以下几部分:
139
140- 声明一个完成量(可以在栈中/使用kmalloc/使用数组)
141- 使用wait_for_completion等待事件完成
142- 使用complete唤醒等待的进程
143
144&emsp;&emsp; 等待操作
145```c
146void wait_fun() {
147    DECLARE_COMPLETION_ON_STACK(comp);  // 声明一个completion
148
149    // .... do somethind here
150    // 大部分情况是你使用kthread_run()创建了另一个线程
151    // 你需要把comp变量传给这个线程, 然后当前线程就会等待他的完成
152
153    if (!try_wait_for_completion(&comp))  // 进入等待
154        wait_for_completion(&comp);
155}
156```
157
158&emsp;&emsp; 完成操作
159```c
160void kthread_fun(struct completion *comp) {
161    // ...... 做一些事  .......
162    // 这里你确定你完成了目标事件
163
164    complete(&comp);
165    // 或者你使用complete_all
166    complete_all(&comp);
167}
168```
169
170### 更多用法
171&emsp;&emsp; kernel/sched/completion.c文件夹中,你可以看到 __test 开头的几个函数,他们是completion模块的测试代码,基本覆盖了completion的大部分函数.你可以在这里查询函数使用方法.
172
173### 初始化完成量
174&emsp;&emsp; 函数`completion_init(struct completion *x)`提供了初始化completion的功能。当你使用`DECLARE_COMPLETION_ON_STACK`来创建(在栈上创建)的时候,会自动初始化.
175
176### 关于完成量的wait系列函数
177
178| 函数名                                 | 解释                                                          |
179| ----------------------------------- | ----------------------------------------------------------- |
180| wait_for_completion(struct completion *x)       | 将当前进程挂起,并设置挂起状态为PROC_UNINTERRUPTIBLE。                     |
181| wait_for_completion_timeout(struct completion *x, long timeout)  | 将当前进程挂起,并设置挂起状态为PROC_UNINTERRUPTIBLE。当等待timeout时间(jiffies时间片)之后,自动唤醒进程。 |
182| wait_for_completion_interruptible(struct completion *x) | 将当前进程挂起,并设置挂起状态为PROC_INTERRUPTIBLE。                          |
183| wait_for_completion_interruptible_timeout(struct completion *x, long timeout) | 将当前进程挂起,并设置挂起状态为PROC_INTERRUPTIBLE。当等待timeout时间(jiffies时间片)之后,自动唤醒进程。                         |
184| wait_for_multicompletion(struct completion x[], int n)| 将当前进程挂起,并设置挂起状态为PROC_UNINTERRUPTIBLE。(等待数组里面的completion的完成)                     |
185
186
187
188### 关于完成量的complete系列函数
189
190| 函数名                                 | 解释                                                          |
191| ----------------------------------- | ----------------------------------------------------------- |
192| complete(struct completion *x)             | 表明一个事件被完成,从等待队列中唤醒一个进程                     |
193| complete_all(struct completion *x)      | 表明与该completion有关的事件被标记为永久完成,并唤醒等待队列中的所有进程 |
194
195
196### 其他用于查询信息的函数
197| 函数名                                 | 解释                                                          |
198| ----------------------------------- | ----------------------------------------------------------- |
199| completion_done(struct completion *x)            | 查询completion的done变量是不是大于0,如果大于0,返回true;否则返回false。在等待前加上这个函数有可能加速?(暂未经过实验测试,有待证明)                     |
200| try_wait_for_completion(struct completion *x)   | 查询completion的done变量是不是大于0,如果大于0,返回true(同时令done-=1);否则返回false。在等待前加上这个函数有可能加速?(该函数和`completion_done`代码逻辑基本一致,但是会主动令completion的done变量减1)   |
201
202
203