1 .. include:: ../disclaimer-zh_CN.rst
2
3 :Original: Documentation/core-api/kref.rst
4
5 翻译:
6
7 司延腾 Yanteng Si <siyanteng@loongson.cn>
8
9 校译：
10
11 <此处请校译员签名（自愿），我将在下一个版本添加>
12
13 .. _cn_core_api_kref.rst:
14
15 =================================
16 为内核对象添加引用计数器（krefs）
17 =================================
18
19 :作者: Corey Minyard <minyard@acm.org>
20 :作者: Thomas Hellstrom <thellstrom@vmware.com>
21
22 其中很多内容都是从Greg Kroah-Hartman2004年关于krefs的OLS论文和演讲中摘
23 录的，可以在以下网址找到:
24
25 - http://www.kroah.com/linux/talks/ols_2004_kref_paper/Reprint-Kroah-Hartman-OLS2004.pdf
26 - http://www.kroah.com/linux/talks/ols_2004_kref_talk/
27
28 简介
29 ====
30
31 krefs允许你为你的对象添加引用计数器。如果你有在多个地方使用和传递的对象，
32 而你没有refcounts，你的代码几乎肯定是坏的。如果你想要引用计数，krefs是个
33 好办法。
34
35 要使用kref，请在你的数据结构中添加一个，如::
36
37 struct my_data
38 {
39 .
40 .
41 struct kref refcount;
42 .
43 .
44 };
45
46 kref可以出现在数据结构体中的任何地方。
47
48 初始化
49 ======
50
51 你必须在分配kref之后初始化它。 要做到这一点，可以这样调用kref_init::
52
53 struct my_data *data;
54
55 data = kmalloc(sizeof(*data), GFP_KERNEL);
56 if (!data)
57 return -ENOMEM;
58 kref_init(&data->refcount);
59
60 这将kref中的refcount设置为1。
61
62 Kref规则
63 ========
64
65 一旦你有一个初始化的kref，你必须遵循以下规则:
66
67 1) 如果你对一个指针做了一个非临时性的拷贝，特别是如果它可以被传递给另一个执
68 行线程，你必须在传递之前用kref_get()增加refcount::
69
70 kref_get(&data->refcount);
71
72 如果你已经有了一个指向kref-ed结构体的有效指针（refcount不能为零），你
73 可以在没有锁的情况下这样做。
74
75 2) 当你完成对一个指针的处理时，你必须调用kref_put()::
76
77 kref_put(&data->refcount, data_release);
78
79 如果这是对该指针的最后一次引用，释放程序将被调用。如果代码从来没有尝试过
80 在没有已经持有有效指针的情况下获得一个kref-ed结构体的有效指针，那么在没
81 有锁的情况下这样做是安全的。
82
83 3) 如果代码试图获得对一个kref-ed结构体的引用，而不持有一个有效的指针，它必
84 须按顺序访问，在kref_put()期间不能发生kref_get()，并且该结构体在kref_get()
85 期间必须保持有效。
86
87 例如，如果你分配了一些数据，然后将其传递给另一个线程来处理::
88
89 void data_release(struct kref *ref)
90 {
91 struct my_data *data = container_of(ref, struct my_data, refcount);
92 kfree(data);
93 }
94
95 void more_data_handling(void *cb_data)
96 {
97 struct my_data *data = cb_data;
98 .
99 . do stuff with data here
100 .
101 kref_put(&data->refcount, data_release);
102 }
103
104 int my_data_handler(void)
105 {
106 int rv = 0;
107 struct my_data *data;
108 struct task_struct *task;
109 data = kmalloc(sizeof(*data), GFP_KERNEL);
110 if (!data)
111 return -ENOMEM;
112 kref_init(&data->refcount);
113
114 kref_get(&data->refcount);
115 task = kthread_run(more_data_handling, data, "more_data_handling");
116 if (task == ERR_PTR(-ENOMEM)) {
117 rv = -ENOMEM;
118 kref_put(&data->refcount, data_release);
119 goto out;
120 }
121
122 .
123 . do stuff with data here
124 .
125 out:
126 kref_put(&data->refcount, data_release);
127 return rv;
128 }
129
130 这样，两个线程处理数据的顺序并不重要，kref_put()处理知道数据不再被引用并释
131 放它。kref_get()不需要锁，因为我们已经有了一个有效的指针，我们拥有一个
132 refcount。put不需要锁，因为没有任何东西试图在没有持有指针的情况下获取数据。
133
134 在上面的例子中，kref_put()在成功和错误路径中都会被调用2次。这是必要的，因
135 为引用计数被kref_init()和kref_get()递增了2次。
136
137 请注意，规则1中的 "before "是非常重要的。你不应该做类似于::
138
139 task = kthread_run(more_data_handling, data, "more_data_handling");
140 if (task == ERR_PTR(-ENOMEM)) {
141 rv = -ENOMEM;
142 goto out;
143 } else
144 /* BAD BAD BAD - 在交接后得到 */
145 kref_get(&data->refcount);
146
147 不要以为你知道自己在做什么而使用上述构造。首先，你可能不知道自己在做什么。
148 其次，你可能知道自己在做什么（有些情况下涉及到锁，上述做法可能是合法的），
149 但其他不知道自己在做什么的人可能会改变代码或复制代码。这是很危险的作风。请
150 不要这样做。
151
152 在有些情况下，你可以优化get和put。例如，如果你已经完成了一个对象，并且给其
153 他对象排队，或者把它传递给其他对象，那么就没有理由先做一个get，然后再做一个
154 put::
155
156 /* 糟糕的额外获取(get)和输出(put) */
157 kref_get(&obj->ref);
158 enqueue(obj);
159 kref_put(&obj->ref, obj_cleanup);
160
161 只要做enqueue就可以了。 我们随时欢迎对这个问题的评论::
162
163 enqueue(obj);
164 /* 我们已经完成了对obj的处理，所以我们把我们的refcount传给了队列。
165 在这之后不要再碰obj了! */
166
167 最后一条规则（规则3）是最难处理的一条。例如，你有一个每个项目都被krefed的列表，
168 而你希望得到第一个项目。你不能只是从列表中抽出第一个项目，然后kref_get()它。
169 这违反了规则3，因为你还没有持有一个有效的指针。你必须添加一个mutex（或其他锁）。
170 比如说::
171
172 static DEFINE_MUTEX(mutex);
173 static LIST_HEAD(q);
174 struct my_data
175 {
176 struct kref refcount;
177 struct list_head link;
178 };
179
180 static struct my_data *get_entry()
181 {
182 struct my_data *entry = NULL;
183 mutex_lock(&mutex);
184 if (!list_empty(&q)) {
185 entry = container_of(q.next, struct my_data, link);
186 kref_get(&entry->refcount);
187 }
188 mutex_unlock(&mutex);
189 return entry;
190 }
191
192 static void release_entry(struct kref *ref)
193 {
194 struct my_data *entry = container_of(ref, struct my_data, refcount);
195
196 list_del(&entry->link);
197 kfree(entry);
198 }
199
200 static void put_entry(struct my_data *entry)
201 {
202 mutex_lock(&mutex);
203 kref_put(&entry->refcount, release_entry);
204 mutex_unlock(&mutex);
205 }
206
207 如果你不想在整个释放操作过程中持有锁，kref_put()的返回值是有用的。假设你不想在
208 上面的例子中在持有锁的情况下调用kfree()（因为这样做有点无意义）。你可以使用kref_put()，
209 如下所示::
210
211 static void release_entry(struct kref *ref)
212 {
213 /* 所有的工作都是在从kref_put()返回后完成的。*/
214 }
215
216 static void put_entry(struct my_data *entry)
217 {
218 mutex_lock(&mutex);
219 if (kref_put(&entry->refcount, release_entry)) {
220 list_del(&entry->link);
221 mutex_unlock(&mutex);
222 kfree(entry);
223 } else
224 mutex_unlock(&mutex);
225 }
226
227 如果你必须调用其他程序作为释放操作的一部分，而这些程序可能需要很长的时间，或者可
228 能要求相同的锁，那么这真的更有用。请注意，在释放例程中做所有的事情还是比较好的，
229 因为它比较整洁。
230
231 上面的例子也可以用kref_get_unless_zero()来优化，方法如下::
232
233 static struct my_data *get_entry()
234 {
235 struct my_data *entry = NULL;
236 mutex_lock(&mutex);
237 if (!list_empty(&q)) {
238 entry = container_of(q.next, struct my_data, link);
239 if (!kref_get_unless_zero(&entry->refcount))
240 entry = NULL;
241 }
242 mutex_unlock(&mutex);
243 return entry;
244 }
245
246 static void release_entry(struct kref *ref)
247 {
248 struct my_data *entry = container_of(ref, struct my_data, refcount);
249
250 mutex_lock(&mutex);
251 list_del(&entry->link);
252 mutex_unlock(&mutex);
253 kfree(entry);
254 }
255
256 static void put_entry(struct my_data *entry)
257 {
258 kref_put(&entry->refcount, release_entry);
259 }
260
261 这对于在put_entry()中移除kref_put()周围的mutex锁是很有用的，但是重要的是
262 kref_get_unless_zero被封装在查找表中的同一关键部分，否则kref_get_unless_zero
263 可能引用已经释放的内存。注意，在不检查其返回值的情况下使用kref_get_unless_zero
264 是非法的。如果你确信（已经有了一个有效的指针）kref_get_unless_zero()会返回true，
265 那么就用kref_get()代替。
266
267 Krefs和RCU
268 ==========
269
270 函数kref_get_unless_zero也使得在上述例子中使用rcu锁进行查找成为可能::
271
272 struct my_data
273 {
274 struct rcu_head rhead;
275 .
276 struct kref refcount;
277 .
278 .
279 };
280
281 static struct my_data *get_entry_rcu()
282 {
283 struct my_data *entry = NULL;
284 rcu_read_lock();
285 if (!list_empty(&q)) {
286 entry = container_of(q.next, struct my_data, link);
287 if (!kref_get_unless_zero(&entry->refcount))
288 entry = NULL;
289 }
290 rcu_read_unlock();
291 return entry;
292 }
293
294 static void release_entry_rcu(struct kref *ref)
295 {
296 struct my_data *entry = container_of(ref, struct my_data, refcount);
297
298 mutex_lock(&mutex);
299 list_del_rcu(&entry->link);
300 mutex_unlock(&mutex);
301 kfree_rcu(entry, rhead);
302 }
303
304 static void put_entry(struct my_data *entry)
305 {
306 kref_put(&entry->refcount, release_entry_rcu);
307 }
308
309 但要注意的是，在调用release_entry_rcu后，结构kref成员需要在有效内存中保留一个rcu
310 宽限期。这可以通过使用上面的kfree_rcu(entry, rhead)来实现，或者在使用kfree之前
311 调用synchronize_rcu()，但注意synchronize_rcu()可能会睡眠相当长的时间。
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.