Root/Documentation/kref.txt

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

Archive Download this file



interactive