1 .. include:: ../disclaimer-zh_CN.rst 1 .. include:: ../disclaimer-zh_CN.rst
2 2
3 :Original: Documentation/scheduler/completion. 3 :Original: Documentation/scheduler/completion.rst
4 4
5 :翻译: 5 :翻译:
6 6
7 司延腾 Yanteng Si <siyanteng@loongson.cn> 7 司延腾 Yanteng Si <siyanteng@loongson.cn>
8 8
9 :校译: 9 :校译:
10 10
11 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> 11 唐艺舟 Tang Yizhou <tangyeechou@gmail.com>
12 12
13 ======================================= 13 =======================================
14 完成 - "等待完成" 屏障应用程序接 14 完成 - "等待完成" 屏障应用程序接口(API)
15 ======================================= 15 =======================================
16 16
17 简介: 17 简介:
18 ----- 18 -----
19 19
20 如果你有一个或多个线程必须等待 20 如果你有一个或多个线程必须等待某些内核活动达到某个点或某个特定的状态，完成可以为这
21 个问题提供一个无竞争的解决方案 21 个问题提供一个无竞争的解决方案。从语义上讲，它们有点像pthread_barrier()，并且使
22 用的案例类似 22 用的案例类似
23 23
24 完成是一种代码同步机制，它比任 24 完成是一种代码同步机制，它比任何滥用锁/信号量和忙等待循环的行为都要好。当你想用yield()
25 或一些古怪的msleep(1)循环来允许其 25 或一些古怪的msleep(1)循环来允许其它代码继续运行时，你可能想用wait_for_completion*()
26 调用和completion()来代替。 26 调用和completion()来代替。
27 27
28 使用“完成”的好处是，它们有一 28 使用“完成”的好处是，它们有一个良好定义、聚焦的目标，这不仅使得我们很容易理解代码的意图，
29 而且它们也会生成更高效的代码， 29 而且它们也会生成更高效的代码，因为所有线程都可以继续执行，直到真正需要结果的时刻。而且等
30 待和信号都高效的使用了低层调度 30 待和信号都高效的使用了低层调度器的睡眠/唤醒设施。
31 31
32 完成是建立在Linux调度器的等待队 32 完成是建立在Linux调度器的等待队列和唤醒基础设施之上的。等待队列中的线程所等待的
33 事件被简化为 ``struct completion`` 中 33 事件被简化为 ``struct completion`` 中的一个简单标志，被恰如其名地称为‘done’。
34 34
35 由于完成与调度有关，代码可以在k 35 由于完成与调度有关，代码可以在kernel/sched/completion.c中找到。
36 36
37 37
38 用法: 38 用法:
39 ----- 39 -----
40 40
41 使用完成需要三个主要部分: 41 使用完成需要三个主要部分:
42 42
43 - 'struct completion' 同步对象的初始 43 - 'struct completion' 同步对象的初始化
44 - 通过调用wait_for_completion()的一个 44 - 通过调用wait_for_completion()的一个变体来实现等待部分。
45 - 通过调用complete()或complete_all()实 45 - 通过调用complete()或complete_all()实现发信端。
46 46
47 也有一些辅助函数用于检查完成的 47 也有一些辅助函数用于检查完成的状态。请注意，虽然必须先做初始化，但等待和信号部分可以
48 按任何时间顺序出现。也就是说， 48 按任何时间顺序出现。也就是说，一个线程在另一个线程检查是否需要等待它之前，已经将一个
49 完成标记为 "done"，这是完全正常的 49 完成标记为 "done"，这是完全正常的。
50 50
51 要使用完成API，你需要#include <linux/ 51 要使用完成API，你需要#include <linux/completion.h>并创建一个静态或动态的
52 ``struct completion`` 类型的变量，它只 52 ``struct completion`` 类型的变量，它只有两个字段::
53 53
54 struct completion { 54 struct completion {
55 unsigned int done; 55 unsigned int done;
56 wait_queue_head_t wait; 56 wait_queue_head_t wait;
57 }; 57 };
58 58
59 结构体提供了->wait等待队列来放置 59 结构体提供了->wait等待队列来放置任务进行等待（如果有的话），以及->done完成标志来表明它
60 是否完成。 60 是否完成。
61 61
62 完成的命名应当与正在被同步的事 62 完成的命名应当与正在被同步的事件名一致。一个好的例子是::
63 63
64 wait_for_completion(&early_console_add 64 wait_for_completion(&early_console_added);
65 65
66 complete(&early_console_added); 66 complete(&early_console_added);
67 67
68 好的、直观的命名（一如既往地） 68 好的、直观的命名（一如既往地）有助于代码的可读性。将一个完成命名为 ``complete``
69 是没有帮助的，除非其目的是超级 69 是没有帮助的，除非其目的是超级明显的...
70 70
71 71
72 初始化完成: 72 初始化完成:
73 ----------- 73 -----------
74 74
75 动态分配的完成对象最好被嵌入到 75 动态分配的完成对象最好被嵌入到数据结构中，以确保在函数/驱动的生命周期内存活，以防
76 止与异步complete()调用发生竞争。 76 止与异步complete()调用发生竞争。
77 77
78 在使用wait_for_completion()的_timeout()或 78 在使用wait_for_completion()的_timeout()或_killable()/_interruptible()变体
79 时应特别小心，因为必须保证在所 79 时应特别小心，因为必须保证在所有相关活动（complete()或reinit_completion()）发生
80 之前不会发生内存解除分配，即使 80 之前不会发生内存解除分配，即使这些等待函数由于超时或信号触发而过早返回。
81 81
82 动态分配的完成对象的初始化是通 82 动态分配的完成对象的初始化是通过调用init_completion()来完成的::
83 83
84 init_completion(&dynamic_object->done) 84 init_completion(&dynamic_object->done);
85 85
86 在这个调用中，我们初始化 waitqueue 86 在这个调用中，我们初始化 waitqueue 并将 ->done 设置为 0，即“not completed”或
87 “not done”。 87 “not done”。
88 88
89 重新初始化函数reinit_completion()，只 89 重新初始化函数reinit_completion()，只是将->done字段重置为0（“not done”），而
90 不触及等待队列。这个函数的调用 90 不触及等待队列。这个函数的调用者必须确保没有任何令人讨厌的wait_for_completion()
91 调用在并行进行。 91 调用在并行进行。
92 92
93 在同一个完成对象上调用init_completi 93 在同一个完成对象上调用init_completion()两次很可能是一个bug，因为它将队列重新初始
94 化为一个空队列，已排队的任务可 94 化为一个空队列，已排队的任务可能会“丢失”--在这种情况下使用reinit_completion()，但
95 要注意其他竞争。 95 要注意其他竞争。
96 96
97 对于静态声明和初始化，可以使用 97 对于静态声明和初始化，可以使用宏。
98 98
99 对于文件范围内的静态（或全局） 99 对于文件范围内的静态（或全局）声明，你可以使用 DECLARE_COMPLETION()::
100 100
101 static DECLARE_COMPLETION(setup_done); 101 static DECLARE_COMPLETION(setup_done);
102 DECLARE_COMPLETION(setup_done); 102 DECLARE_COMPLETION(setup_done);
103 103
104 注意，在这种情况下，完成在启动 104 注意，在这种情况下，完成在启动时（或模块加载时）被初始化为“not done”，不需要调用
105 init_completion()。 105 init_completion()。
106 106
107 当完成被声明为一个函数中的局部 107 当完成被声明为一个函数中的局部变量时，那么应该总是明确地使用
108 DECLARE_COMPLETION_ONSTACK()来初始化，这 108 DECLARE_COMPLETION_ONSTACK()来初始化，这不仅仅是为了让lockdep正确运行，也是明确表
109 名它有限的使用范围是有意为之并 109 名它有限的使用范围是有意为之并被仔细考虑的::
110 110
111 DECLARE_COMPLETION_ONSTACK(setup_done) 111 DECLARE_COMPLETION_ONSTACK(setup_done)
112 112
113 请注意，当使用完成对象作为局部 113 请注意，当使用完成对象作为局部变量时，你必须敏锐地意识到函数堆栈的短暂生命期：在所有
114 活动（如等待的线程）停止并且完 114 活动（如等待的线程）停止并且完成对象完全未被使用之前，函数不得返回到调用上下文。
115 115
116 再次强调这一点：特别是在使用一 116 再次强调这一点：特别是在使用一些具有更复杂结果的等待API变体时，比如超时或信号
117 （_timeout(), _killable()和_interruptible() 117 （_timeout(), _killable()和_interruptible()）变体，等待可能会提前完成，而对象可
118 能仍在被其他线程使用 - 从wait_on_co 118 能仍在被其他线程使用 - 从wait_on_completion*()调用者函数的返回会取消分配函数栈，如
119 果complete()在其它某线程中完成调用 119 果complete()在其它某线程中完成调用，会引起微小的数据损坏。简单的测试可能不会触发这
120 些类型的竞争。 120 些类型的竞争。
121 121
122 如果不确定的话，使用动态分配的 122 如果不确定的话，使用动态分配的完成对象， 最好是嵌入到其它一些生命周期长的对象中，长到
123 超过使用完成对象的任何辅助线程 123 超过使用完成对象的任何辅助线程的生命周期，或者有一个锁或其他同步机制来确保complete()
124 不会在一个被释放的对象中调用。 124 不会在一个被释放的对象中调用。
125 125
126 在堆栈上单纯地调用DECLARE_COMPLETION( 126 在堆栈上单纯地调用DECLARE_COMPLETION()会触发一个lockdep警告。
127 127
128 等待完成: 128 等待完成:
129 --------- 129 ---------
130 130
131 对于一个线程来说，要等待一些并 131 对于一个线程来说，要等待一些并发活动的完成，它要在初始化的完成结构体上调用
132 wait_for_completion():: 132 wait_for_completion()::
133 133
134 void wait_for_completion(struct comple 134 void wait_for_completion(struct completion *done)
135 135
136 一个典型的使用场景是:: 136 一个典型的使用场景是::
137 137
138 CPU#1 138 CPU#1 CPU#2
139 139
140 struct completion setup_done; 140 struct completion setup_done;
141 141
142 init_completion(&setup_done); 142 init_completion(&setup_done);
143 initialize_work(...,&setup_done,...); 143 initialize_work(...,&setup_done,...);
144 144
145 /* run non-dependent code */ 145 /* run non-dependent code */ /* do setup */
146 146
147 wait_for_completion(&setup_done); 147 wait_for_completion(&setup_done); complete(setup_done);
148 148
149 这并不意味着调用wait_for_completion() 149 这并不意味着调用wait_for_completion()和complete()有任何特定的时间顺序--如果调
150 用complete()发生在调用wait_for_completio 150 用complete()发生在调用wait_for_completion()之前，那么等待方将立即继续执行，因为
151 所有的依赖都得到了满足；如果没 151 所有的依赖都得到了满足；如果没有，它将阻塞，直到complete()发出完成的信号。
152 152
153 注意，wait_for_completion()是在调用spin 153 注意，wait_for_completion()是在调用spin_lock_irq()/spin_unlock_irq()，所以
154 只有当你知道中断被启用时才能安 154 只有当你知道中断被启用时才能安全地调用它。从IRQs-off的原子上下文中调用它将导致难以检
155 测的错误的中断启用。 155 测的错误的中断启用。
156 156
157 默认行为是不带超时的等待，并将 157 默认行为是不带超时的等待，并将任务标记为“UNINTERRUPTIBLE”状态。wait_for_completion()
158 及其变体只有在进程上下文中才是 158 及其变体只有在进程上下文中才是安全的（因为它们可以休眠），但在原子上下文、中断上下文、IRQ
159 被禁用或抢占被禁用的情况下是不 159 被禁用或抢占被禁用的情况下是不安全的--关于在原子/中断上下文中处理完成的问题，还请看下面的
160 try_wait_for_completion()。 160 try_wait_for_completion()。
161 161
162 由于wait_for_completion()的所有变体都 162 由于wait_for_completion()的所有变体都可能（很明显）阻塞很长时间，这取决于它们所等
163 待的活动的性质，所以在大多数情 163 待的活动的性质，所以在大多数情况下，你可能不想在持有mutex锁的情况下调用它。
164 164
165 165
166 wait_for_completion*()可用的变体: 166 wait_for_completion*()可用的变体:
167 --------------------------------- 167 ---------------------------------
168 168
169 下面的变体都会返回状态，在大多 169 下面的变体都会返回状态，在大多数(/所有)情况下都应该检查这个状态--在故意不检查状态的情
170 况下，你可能要做一个说明(例如， 170 况下，你可能要做一个说明(例如，见arch/arm/kernel/smp.c:__cpu_up())。
171 171
172 一个常见的问题是不准确的返回类 172 一个常见的问题是不准确的返回类型赋值，所以要注意将返回值赋值给适当类型的变量。
173 173
174 检查返回值的具体含义也可能被发 174 检查返回值的具体含义也可能被发现是相当不准确的，例如，像这样的构造::
175 175
176 if (!wait_for_completion_interruptible 176 if (!wait_for_completion_interruptible_timeout(...))
177 177
178 ...会在成功完成和中断的情况下执 178 ...会在成功完成和中断的情况下执行相同的代码路径--这可能不是你想要的结果::
179 179
180 int wait_for_completion_interruptible( 180 int wait_for_completion_interruptible(struct completion *done)
181 181
182 这个函数在任务等待时标记为TASK_IN 182 这个函数在任务等待时标记为TASK_INTERRUPTIBLE。如果在等待期间收到信号，它将返回
183 -ERESTARTSYS；否则为0:: 183 -ERESTARTSYS；否则为0::
184 184
185 unsigned long wait_for_completion_time 185 unsigned long wait_for_completion_timeout(struct completion *done, unsigned long timeout)
186 186
187 该任务被标记为TASK_UNINTERRUPTIBLE， 187 该任务被标记为TASK_UNINTERRUPTIBLE，并将最多超时等待“timeout”个jiffies。如果超时发生，则
188 返回0，否则返回剩余的时间（但至 188 返回0，否则返回剩余的时间（但至少是1）。
189 189
190 超时最好用msecs_to_jiffies()或usecs_to_j 190 超时最好用msecs_to_jiffies()或usecs_to_jiffies()计算，以使代码在很大程度上不受
191 HZ的影响。 191 HZ的影响。
192 192
193 如果返回的超时值被故意忽略，那 193 如果返回的超时值被故意忽略，那么注释应该解释原因
194 （例如，见drivers/mfd/wm8350-core.c wm835 194 （例如，见drivers/mfd/wm8350-core.c wm8350_read_auxadc()::
195 195
196 long wait_for_completion_interruptible 196 long wait_for_completion_interruptible_timeout(struct completion *done, unsigned long timeout)
197 197
198 这个函数传递一个以jiffies为单位的 198 这个函数传递一个以jiffies为单位的超时，并将任务标记为TASK_INTERRUPTIBLE。如果收到
199 信号，则返回-ERESTARTSYS；否则，如 199 信号，则返回-ERESTARTSYS；否则，如果完成超时，则返回0；如果完成了，则返回剩余的时间
200 （jiffies）。 200 （jiffies）。
201 201
202 更多的变体包括_killable，它使用TASK 202 更多的变体包括_killable，它使用TASK_KILLABLE作为指定的任务状态，如果它被中断，将返
203 回-ERESTARTSYS，如果完成了，则返回0 203 回-ERESTARTSYS，如果完成了，则返回0。它也有一个_timeout变体::
204 204
205 long wait_for_completion_killable(stru 205 long wait_for_completion_killable(struct completion *done)
206 long wait_for_completion_killable_time 206 long wait_for_completion_killable_timeout(struct completion *done, unsigned long timeout)
207 207
208 wait_for_completion_io()的_io变体的行为 208 wait_for_completion_io()的_io变体的行为与非_io变体相同，只是将等待时间计为“IO等待”，
209 这对任务在调度/IO统计中的计算方 209 这对任务在调度/IO统计中的计算方式有影响::
210 210
211 void wait_for_completion_io(struct com 211 void wait_for_completion_io(struct completion *done)
212 unsigned long wait_for_completion_io_t 212 unsigned long wait_for_completion_io_timeout(struct completion *done, unsigned long timeout)
213 213
214 214
215 对完成发信号: 215 对完成发信号:
216 ------------- 216 -------------
217 217
218 一个线程想要发出信号通知继续的 218 一个线程想要发出信号通知继续的条件已经达到，就会调用complete()，向其中一个等待者发出信
219 号表明它可以继续:: 219 号表明它可以继续::
220 220
221 void complete(struct completion *done) 221 void complete(struct completion *done)
222 222
223 ... or calls complete_all() to signal all curr 223 ... or calls complete_all() to signal all current and future waiters::
224 224
225 void complete_all(struct completion *d 225 void complete_all(struct completion *done)
226 226
227 即使在线程开始等待之前就发出了 227 即使在线程开始等待之前就发出了完成的信号，信号传递也会继续进行。这是通过等待者
228 “consuming”（递减）“struct completio 228 “consuming”（递减）“struct completion” 的完成字段来实现的。等待的线程唤醒的顺序
229 与它们被排队的顺序相同（FIFO顺序 229 与它们被排队的顺序相同（FIFO顺序）。
230 230
231 如果多次调用complete()，那么这将允 231 如果多次调用complete()，那么这将允许该数量的等待者继续进行--每次调用complete()将
232 简单地增加已完成的字段。但多次 232 简单地增加已完成的字段。但多次调用complete_all()是一个错误。complete()和
233 complete_all()都可以在IRQ/atomic上下文 233 complete_all()都可以在IRQ/atomic上下文中安全调用。
234 234
235 在任何时候，只能有一个线程在一 235 在任何时候，只能有一个线程在一个特定的 “struct completion”上调用 complete() 或
236 complete_all() - 通过等待队列自旋锁 236 complete_all() - 通过等待队列自旋锁进行序列化。任何对 complete() 或
237 complete_all() 的并发调用都可能是一 237 complete_all() 的并发调用都可能是一个设计错误。
238 238
239 从IRQ上下文中发出完成信号 是可行 239 从IRQ上下文中发出完成信号 是可行的，因为它将正确地用
240 spin_lock_irqsave()/spin_unlock_irqrestore() 240 spin_lock_irqsave()/spin_unlock_irqrestore()执行锁操作
241 241
242 242
243 try_wait_for_completion()/completion_done(): 243 try_wait_for_completion()/completion_done():
244 -------------------------------------------- 244 --------------------------------------------
245 245
246 try_wait_for_completion()函数不会将线程 246 try_wait_for_completion()函数不会将线程放在等待队列中，而是在需要排队（阻塞）线
247 程时返回false，否则会消耗一个已 247 程时返回false，否则会消耗一个已发布的完成并返回true::
248 248
249 bool try_wait_for_completion(struct co 249 bool try_wait_for_completion(struct completion *done)
250 250
251 最后，为了在不以任何方式改变完 251 最后，为了在不以任何方式改变完成的情况下检查完成的状态，可以调用completion_done()，
252 如果没有发布的完成尚未被等待者 252 如果没有发布的完成尚未被等待者消耗，则返回false（意味着存在等待者），否则返回true::
253 253
254 bool completion_done(struct completion 254 bool completion_done(struct completion *done)
255 255
256 try_wait_for_completion()和completion_done() 256 try_wait_for_completion()和completion_done()都可以在IRQ或原子上下文中安全调用。
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.