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 31krefs允许你为你的对象添加引用计数器。如果你有在多个地方使用和传递的对象， 32而你没有refcounts，你的代码几乎肯定是坏的。如果你想要引用计数，krefs是个 33好办法。 34 35要使用kref，请在你的数据结构中添加一个，如:: 36 37 struct my_data 38 { 39 . 40 . 41 struct kref refcount; 42 . 43 . 44 }; 45 46kref可以出现在数据结构体中的任何地方。 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 62Kref规则 63======== 64 65一旦你有一个初始化的kref，你必须遵循以下规则: 66 671) 如果你对一个指针做了一个非临时性的拷贝，特别是如果它可以被传递给另一个执 68 行线程，你必须在传递之前用kref_get()增加refcount:: 69 70 kref_get(&data->refcount); 71 72 如果你已经有了一个指向kref-ed结构体的有效指针（refcount不能为零），你 73 可以在没有锁的情况下这样做。 74 752) 当你完成对一个指针的处理时，你必须调用kref_put():: 76 77 kref_put(&data->refcount, data_release); 78 79 如果这是对该指针的最后一次引用，释放程序将被调用。如果代码从来没有尝试过 80 在没有已经持有有效指针的情况下获得一个kref-ed结构体的有效指针，那么在没 81 有锁的情况下这样做是安全的。 82 833) 如果代码试图获得对一个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()不需要锁，因为我们已经有了一个有效的指针，我们拥有一个 132refcount。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，然后再做一个 154put:: 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锁是很有用的，但是重要的是 262kref_get_unless_zero被封装在查找表中的同一关键部分，否则kref_get_unless_zero 263可能引用已经释放的内存。注意，在不检查其返回值的情况下使用kref_get_unless_zero 264是非法的。如果你确信（已经有了一个有效的指针）kref_get_unless_zero()会返回true， 265那么就用kref_get()代替。 266 267Krefs和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()可能会睡眠相当长的时间。 312