kref.rst 9.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323
  1. ===================================================
  2. Adding reference counters (krefs) to kernel objects
  3. ===================================================
  4. :Author: Corey Minyard <minyard@acm.org>
  5. :Author: Thomas Hellstrom <thellstrom@vmware.com>
  6. A lot of this was lifted from Greg Kroah-Hartman's 2004 OLS paper and
  7. presentation on krefs, which can be found at:
  8. - http://www.kroah.com/linux/talks/ols_2004_kref_paper/Reprint-Kroah-Hartman-OLS2004.pdf
  9. - http://www.kroah.com/linux/talks/ols_2004_kref_talk/
  10. Introduction
  11. ============
  12. krefs allow you to add reference counters to your objects. If you
  13. have objects that are used in multiple places and passed around, and
  14. you don't have refcounts, your code is almost certainly broken. If
  15. you want refcounts, krefs are the way to go.
  16. To use a kref, add one to your data structures like::
  17. struct my_data
  18. {
  19. .
  20. .
  21. struct kref refcount;
  22. .
  23. .
  24. };
  25. The kref can occur anywhere within the data structure.
  26. Initialization
  27. ==============
  28. You must initialize the kref after you allocate it. To do this, call
  29. kref_init as so::
  30. struct my_data *data;
  31. data = kmalloc(sizeof(*data), GFP_KERNEL);
  32. if (!data)
  33. return -ENOMEM;
  34. kref_init(&data->refcount);
  35. This sets the refcount in the kref to 1.
  36. Kref rules
  37. ==========
  38. Once you have an initialized kref, you must follow the following
  39. rules:
  40. 1) If you make a non-temporary copy of a pointer, especially if
  41. it can be passed to another thread of execution, you must
  42. increment the refcount with kref_get() before passing it off::
  43. kref_get(&data->refcount);
  44. If you already have a valid pointer to a kref-ed structure (the
  45. refcount cannot go to zero) you may do this without a lock.
  46. 2) When you are done with a pointer, you must call kref_put()::
  47. kref_put(&data->refcount, data_release);
  48. If this is the last reference to the pointer, the release
  49. routine will be called. If the code never tries to get
  50. a valid pointer to a kref-ed structure without already
  51. holding a valid pointer, it is safe to do this without
  52. a lock.
  53. 3) If the code attempts to gain a reference to a kref-ed structure
  54. without already holding a valid pointer, it must serialize access
  55. where a kref_put() cannot occur during the kref_get(), and the
  56. structure must remain valid during the kref_get().
  57. For example, if you allocate some data and then pass it to another
  58. thread to process::
  59. void data_release(struct kref *ref)
  60. {
  61. struct my_data *data = container_of(ref, struct my_data, refcount);
  62. kfree(data);
  63. }
  64. void more_data_handling(void *cb_data)
  65. {
  66. struct my_data *data = cb_data;
  67. .
  68. . do stuff with data here
  69. .
  70. kref_put(&data->refcount, data_release);
  71. }
  72. int my_data_handler(void)
  73. {
  74. int rv = 0;
  75. struct my_data *data;
  76. struct task_struct *task;
  77. data = kmalloc(sizeof(*data), GFP_KERNEL);
  78. if (!data)
  79. return -ENOMEM;
  80. kref_init(&data->refcount);
  81. kref_get(&data->refcount);
  82. task = kthread_run(more_data_handling, data, "more_data_handling");
  83. if (task == ERR_PTR(-ENOMEM)) {
  84. rv = -ENOMEM;
  85. kref_put(&data->refcount, data_release);
  86. goto out;
  87. }
  88. .
  89. . do stuff with data here
  90. .
  91. out:
  92. kref_put(&data->refcount, data_release);
  93. return rv;
  94. }
  95. This way, it doesn't matter what order the two threads handle the
  96. data, the kref_put() handles knowing when the data is not referenced
  97. any more and releasing it. The kref_get() does not require a lock,
  98. since we already have a valid pointer that we own a refcount for. The
  99. put needs no lock because nothing tries to get the data without
  100. already holding a pointer.
  101. In the above example, kref_put() will be called 2 times in both success
  102. and error paths. This is necessary because the reference count got
  103. incremented 2 times by kref_init() and kref_get().
  104. Note that the "before" in rule 1 is very important. You should never
  105. do something like::
  106. task = kthread_run(more_data_handling, data, "more_data_handling");
  107. if (task == ERR_PTR(-ENOMEM)) {
  108. rv = -ENOMEM;
  109. goto out;
  110. } else
  111. /* BAD BAD BAD - get is after the handoff */
  112. kref_get(&data->refcount);
  113. Don't assume you know what you are doing and use the above construct.
  114. First of all, you may not know what you are doing. Second, you may
  115. know what you are doing (there are some situations where locking is
  116. involved where the above may be legal) but someone else who doesn't
  117. know what they are doing may change the code or copy the code. It's
  118. bad style. Don't do it.
  119. There are some situations where you can optimize the gets and puts.
  120. For instance, if you are done with an object and enqueuing it for
  121. something else or passing it off to something else, there is no reason
  122. to do a get then a put::
  123. /* Silly extra get and put */
  124. kref_get(&obj->ref);
  125. enqueue(obj);
  126. kref_put(&obj->ref, obj_cleanup);
  127. Just do the enqueue. A comment about this is always welcome::
  128. enqueue(obj);
  129. /* We are done with obj, so we pass our refcount off
  130. to the queue. DON'T TOUCH obj AFTER HERE! */
  131. The last rule (rule 3) is the nastiest one to handle. Say, for
  132. instance, you have a list of items that are each kref-ed, and you wish
  133. to get the first one. You can't just pull the first item off the list
  134. and kref_get() it. That violates rule 3 because you are not already
  135. holding a valid pointer. You must add a mutex (or some other lock).
  136. For instance::
  137. static DEFINE_MUTEX(mutex);
  138. static LIST_HEAD(q);
  139. struct my_data
  140. {
  141. struct kref refcount;
  142. struct list_head link;
  143. };
  144. static struct my_data *get_entry()
  145. {
  146. struct my_data *entry = NULL;
  147. mutex_lock(&mutex);
  148. if (!list_empty(&q)) {
  149. entry = container_of(q.next, struct my_data, link);
  150. kref_get(&entry->refcount);
  151. }
  152. mutex_unlock(&mutex);
  153. return entry;
  154. }
  155. static void release_entry(struct kref *ref)
  156. {
  157. struct my_data *entry = container_of(ref, struct my_data, refcount);
  158. list_del(&entry->link);
  159. kfree(entry);
  160. }
  161. static void put_entry(struct my_data *entry)
  162. {
  163. mutex_lock(&mutex);
  164. kref_put(&entry->refcount, release_entry);
  165. mutex_unlock(&mutex);
  166. }
  167. The kref_put() return value is useful if you do not want to hold the
  168. lock during the whole release operation. Say you didn't want to call
  169. kfree() with the lock held in the example above (since it is kind of
  170. pointless to do so). You could use kref_put() as follows::
  171. static void release_entry(struct kref *ref)
  172. {
  173. /* All work is done after the return from kref_put(). */
  174. }
  175. static void put_entry(struct my_data *entry)
  176. {
  177. mutex_lock(&mutex);
  178. if (kref_put(&entry->refcount, release_entry)) {
  179. list_del(&entry->link);
  180. mutex_unlock(&mutex);
  181. kfree(entry);
  182. } else
  183. mutex_unlock(&mutex);
  184. }
  185. This is really more useful if you have to call other routines as part
  186. of the free operations that could take a long time or might claim the
  187. same lock. Note that doing everything in the release routine is still
  188. preferred as it is a little neater.
  189. The above example could also be optimized using kref_get_unless_zero() in
  190. the following way::
  191. static struct my_data *get_entry()
  192. {
  193. struct my_data *entry = NULL;
  194. mutex_lock(&mutex);
  195. if (!list_empty(&q)) {
  196. entry = container_of(q.next, struct my_data, link);
  197. if (!kref_get_unless_zero(&entry->refcount))
  198. entry = NULL;
  199. }
  200. mutex_unlock(&mutex);
  201. return entry;
  202. }
  203. static void release_entry(struct kref *ref)
  204. {
  205. struct my_data *entry = container_of(ref, struct my_data, refcount);
  206. mutex_lock(&mutex);
  207. list_del(&entry->link);
  208. mutex_unlock(&mutex);
  209. kfree(entry);
  210. }
  211. static void put_entry(struct my_data *entry)
  212. {
  213. kref_put(&entry->refcount, release_entry);
  214. }
  215. Which is useful to remove the mutex lock around kref_put() in put_entry(), but
  216. it's important that kref_get_unless_zero is enclosed in the same critical
  217. section that finds the entry in the lookup table,
  218. otherwise kref_get_unless_zero may reference already freed memory.
  219. Note that it is illegal to use kref_get_unless_zero without checking its
  220. return value. If you are sure (by already having a valid pointer) that
  221. kref_get_unless_zero() will return true, then use kref_get() instead.
  222. Krefs and RCU
  223. =============
  224. The function kref_get_unless_zero also makes it possible to use rcu
  225. locking for lookups in the above example::
  226. struct my_data
  227. {
  228. struct rcu_head rhead;
  229. .
  230. struct kref refcount;
  231. .
  232. .
  233. };
  234. static struct my_data *get_entry_rcu()
  235. {
  236. struct my_data *entry = NULL;
  237. rcu_read_lock();
  238. if (!list_empty(&q)) {
  239. entry = container_of(q.next, struct my_data, link);
  240. if (!kref_get_unless_zero(&entry->refcount))
  241. entry = NULL;
  242. }
  243. rcu_read_unlock();
  244. return entry;
  245. }
  246. static void release_entry_rcu(struct kref *ref)
  247. {
  248. struct my_data *entry = container_of(ref, struct my_data, refcount);
  249. mutex_lock(&mutex);
  250. list_del_rcu(&entry->link);
  251. mutex_unlock(&mutex);
  252. kfree_rcu(entry, rhead);
  253. }
  254. static void put_entry(struct my_data *entry)
  255. {
  256. kref_put(&entry->refcount, release_entry_rcu);
  257. }
  258. But note that the struct kref member needs to remain in valid memory for a
  259. rcu grace period after release_entry_rcu was called. That can be accomplished
  260. by using kfree_rcu(entry, rhead) as done above, or by calling synchronize_rcu()
  261. before using kfree, but note that synchronize_rcu() may sleep for a
  262. substantial amount of time.