Documentation/translations/zh_CN/core-api/kref.rst

   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()可能会睡眠相当长的时间。