1 ===================================================
2 Adding reference counters (krefs) to kernel objects
3 ===================================================
5 :Author: Corey Minyard <minyard@acm.org>
6 :Author: Thomas Hellstrom <thellstrom@vmware.com>
8 A lot of this was lifted from Greg Kroah-Hartman's 2004 OLS paper and
9 presentation on krefs, which can be found at:
11 - http://www.kroah.com/linux/talks/ols_2004_kref_paper/Reprint-Kroah-Hartman-OLS2004.pdf
12 - http://www.kroah.com/linux/talks/ols_2004_kref_talk/
17 krefs allow you to add reference counters to your objects. If you
18 have objects that are used in multiple places and passed around, and
19 you don't have refcounts, your code is almost certainly broken. If
20 you want refcounts, krefs are the way to go.
22 To use a kref, add one to your data structures like::
33 The kref can occur anywhere within the data structure.
38 You must initialize the kref after you allocate it. To do this, call
43 data = kmalloc(sizeof(*data), GFP_KERNEL);
46 kref_init(&data->refcount);
48 This sets the refcount in the kref to 1.
53 Once you have an initialized kref, you must follow the following
56 1) If you make a non-temporary copy of a pointer, especially if
57 it can be passed to another thread of execution, you must
58 increment the refcount with kref_get() before passing it off::
60 kref_get(&data->refcount);
62 If you already have a valid pointer to a kref-ed structure (the
63 refcount cannot go to zero) you may do this without a lock.
65 2) When you are done with a pointer, you must call kref_put()::
67 kref_put(&data->refcount, data_release);
69 If this is the last reference to the pointer, the release
70 routine will be called. If the code never tries to get
71 a valid pointer to a kref-ed structure without already
72 holding a valid pointer, it is safe to do this without
75 3) If the code attempts to gain a reference to a kref-ed structure
76 without already holding a valid pointer, it must serialize access
77 where a kref_put() cannot occur during the kref_get(), and the
78 structure must remain valid during the kref_get().
80 For example, if you allocate some data and then pass it to another
83 void data_release(struct kref *ref)
85 struct my_data *data = container_of(ref, struct my_data, refcount);
89 void more_data_handling(void *cb_data)
91 struct my_data *data = cb_data;
93 . do stuff with data here
95 kref_put(&data->refcount, data_release);
98 int my_data_handler(void)
101 struct my_data *data;
102 struct task_struct *task;
103 data = kmalloc(sizeof(*data), GFP_KERNEL);
106 kref_init(&data->refcount);
108 kref_get(&data->refcount);
109 task = kthread_run(more_data_handling, data, "more_data_handling");
110 if (task == ERR_PTR(-ENOMEM)) {
112 kref_put(&data->refcount, data_release);
117 . do stuff with data here
120 kref_put(&data->refcount, data_release);
124 This way, it doesn't matter what order the two threads handle the
125 data, the kref_put() handles knowing when the data is not referenced
126 any more and releasing it. The kref_get() does not require a lock,
127 since we already have a valid pointer that we own a refcount for. The
128 put needs no lock because nothing tries to get the data without
129 already holding a pointer.
131 Note that the "before" in rule 1 is very important. You should never
134 task = kthread_run(more_data_handling, data, "more_data_handling");
135 if (task == ERR_PTR(-ENOMEM)) {
139 /* BAD BAD BAD - get is after the handoff */
140 kref_get(&data->refcount);
142 Don't assume you know what you are doing and use the above construct.
143 First of all, you may not know what you are doing. Second, you may
144 know what you are doing (there are some situations where locking is
145 involved where the above may be legal) but someone else who doesn't
146 know what they are doing may change the code or copy the code. It's
147 bad style. Don't do it.
149 There are some situations where you can optimize the gets and puts.
150 For instance, if you are done with an object and enqueuing it for
151 something else or passing it off to something else, there is no reason
152 to do a get then a put::
154 /* Silly extra get and put */
157 kref_put(&obj->ref, obj_cleanup);
159 Just do the enqueue. A comment about this is always welcome::
162 /* We are done with obj, so we pass our refcount off
163 to the queue. DON'T TOUCH obj AFTER HERE! */
165 The last rule (rule 3) is the nastiest one to handle. Say, for
166 instance, you have a list of items that are each kref-ed, and you wish
167 to get the first one. You can't just pull the first item off the list
168 and kref_get() it. That violates rule 3 because you are not already
169 holding a valid pointer. You must add a mutex (or some other lock).
172 static DEFINE_MUTEX(mutex);
176 struct kref refcount;
177 struct list_head link;
180 static struct my_data *get_entry()
182 struct my_data *entry = NULL;
184 if (!list_empty(&q)) {
185 entry = container_of(q.next, struct my_data, link);
186 kref_get(&entry->refcount);
188 mutex_unlock(&mutex);
192 static void release_entry(struct kref *ref)
194 struct my_data *entry = container_of(ref, struct my_data, refcount);
196 list_del(&entry->link);
200 static void put_entry(struct my_data *entry)
203 kref_put(&entry->refcount, release_entry);
204 mutex_unlock(&mutex);
207 The kref_put() return value is useful if you do not want to hold the
208 lock during the whole release operation. Say you didn't want to call
209 kfree() with the lock held in the example above (since it is kind of
210 pointless to do so). You could use kref_put() as follows::
212 static void release_entry(struct kref *ref)
214 /* All work is done after the return from kref_put(). */
217 static void put_entry(struct my_data *entry)
220 if (kref_put(&entry->refcount, release_entry)) {
221 list_del(&entry->link);
222 mutex_unlock(&mutex);
225 mutex_unlock(&mutex);
228 This is really more useful if you have to call other routines as part
229 of the free operations that could take a long time or might claim the
230 same lock. Note that doing everything in the release routine is still
231 preferred as it is a little neater.
233 The above example could also be optimized using kref_get_unless_zero() in
236 static struct my_data *get_entry()
238 struct my_data *entry = NULL;
240 if (!list_empty(&q)) {
241 entry = container_of(q.next, struct my_data, link);
242 if (!kref_get_unless_zero(&entry->refcount))
245 mutex_unlock(&mutex);
249 static void release_entry(struct kref *ref)
251 struct my_data *entry = container_of(ref, struct my_data, refcount);
254 list_del(&entry->link);
255 mutex_unlock(&mutex);
259 static void put_entry(struct my_data *entry)
261 kref_put(&entry->refcount, release_entry);
264 Which is useful to remove the mutex lock around kref_put() in put_entry(), but
265 it's important that kref_get_unless_zero is enclosed in the same critical
266 section that finds the entry in the lookup table,
267 otherwise kref_get_unless_zero may reference already freed memory.
268 Note that it is illegal to use kref_get_unless_zero without checking its
269 return value. If you are sure (by already having a valid pointer) that
270 kref_get_unless_zero() will return true, then use kref_get() instead.
275 The function kref_get_unless_zero also makes it possible to use rcu
276 locking for lookups in the above example::
280 struct rcu_head rhead;
282 struct kref refcount;
287 static struct my_data *get_entry_rcu()
289 struct my_data *entry = NULL;
291 if (!list_empty(&q)) {
292 entry = container_of(q.next, struct my_data, link);
293 if (!kref_get_unless_zero(&entry->refcount))
300 static void release_entry_rcu(struct kref *ref)
302 struct my_data *entry = container_of(ref, struct my_data, refcount);
305 list_del_rcu(&entry->link);
306 mutex_unlock(&mutex);
307 kfree_rcu(entry, rhead);
310 static void put_entry(struct my_data *entry)
312 kref_put(&entry->refcount, release_entry_rcu);
315 But note that the struct kref member needs to remain in valid memory for a
316 rcu grace period after release_entry_rcu was called. That can be accomplished
317 by using kfree_rcu(entry, rhead) as done above, or by calling synchronize_rcu()
318 before using kfree, but note that synchronize_rcu() may sleep for a
319 substantial amount of time.