]> git.proxmox.com Git - mirror_ubuntu-artful-kernel.git/blame - Documentation/kref.txt
Merge tag 'sound-4.12-rc7' of git://git.kernel.org/pub/scm/linux/kernel/git/tiwai...
[mirror_ubuntu-artful-kernel.git] / Documentation / kref.txt
CommitLineData
5c11c520
CM
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 .
b7cc4a87 70 kref_put(&data->refcount, data_release);
5c11c520
CM
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;
fd0f50db 87 kref_put(&data->refcount, data_release);
5c11c520
CM
88 goto out;
89 }
90
91 .
92 . do stuff with data here
93 .
94 out:
95 kref_put(&data->refcount, data_release);
96 return rv;
97}
98
99This way, it doesn't matter what order the two threads handle the
100data, the kref_put() handles knowing when the data is not referenced
101any more and releasing it. The kref_get() does not require a lock,
102since we already have a valid pointer that we own a refcount for. The
103put needs no lock because nothing tries to get the data without
104already holding a pointer.
105
106Note that the "before" in rule 1 is very important. You should never
107do something like:
108
109 task = kthread_run(more_data_handling, data, "more_data_handling");
110 if (task == ERR_PTR(-ENOMEM)) {
111 rv = -ENOMEM;
112 goto out;
113 } else
114 /* BAD BAD BAD - get is after the handoff */
115 kref_get(&data->refcount);
116
117Don't assume you know what you are doing and use the above construct.
118First of all, you may not know what you are doing. Second, you may
119know what you are doing (there are some situations where locking is
120involved where the above may be legal) but someone else who doesn't
121know what they are doing may change the code or copy the code. It's
122bad style. Don't do it.
123
124There are some situations where you can optimize the gets and puts.
125For instance, if you are done with an object and enqueuing it for
126something else or passing it off to something else, there is no reason
127to do a get then a put:
128
129 /* Silly extra get and put */
130 kref_get(&obj->ref);
131 enqueue(obj);
132 kref_put(&obj->ref, obj_cleanup);
133
134Just do the enqueue. A comment about this is always welcome:
135
136 enqueue(obj);
137 /* We are done with obj, so we pass our refcount off
138 to the queue. DON'T TOUCH obj AFTER HERE! */
139
140The last rule (rule 3) is the nastiest one to handle. Say, for
141instance, you have a list of items that are each kref-ed, and you wish
142to get the first one. You can't just pull the first item off the list
143and kref_get() it. That violates rule 3 because you are not already
1373bed3
DW
144holding a valid pointer. You must add a mutex (or some other lock).
145For instance:
5c11c520 146
1373bed3 147static DEFINE_MUTEX(mutex);
5c11c520
CM
148static LIST_HEAD(q);
149struct my_data
150{
151 struct kref refcount;
152 struct list_head link;
153};
154
155static struct my_data *get_entry()
156{
157 struct my_data *entry = NULL;
1373bed3 158 mutex_lock(&mutex);
5c11c520 159 if (!list_empty(&q)) {
d5c97c10 160 entry = container_of(q.next, struct my_data, link);
5c11c520
CM
161 kref_get(&entry->refcount);
162 }
1373bed3 163 mutex_unlock(&mutex);
5c11c520
CM
164 return entry;
165}
166
167static void release_entry(struct kref *ref)
168{
169 struct my_data *entry = container_of(ref, struct my_data, refcount);
170
171 list_del(&entry->link);
172 kfree(entry);
173}
174
175static void put_entry(struct my_data *entry)
176{
1373bed3 177 mutex_lock(&mutex);
5c11c520 178 kref_put(&entry->refcount, release_entry);
1373bed3 179 mutex_unlock(&mutex);
5c11c520
CM
180}
181
182The kref_put() return value is useful if you do not want to hold the
183lock during the whole release operation. Say you didn't want to call
184kfree() with the lock held in the example above (since it is kind of
185pointless to do so). You could use kref_put() as follows:
186
187static void release_entry(struct kref *ref)
188{
189 /* All work is done after the return from kref_put(). */
190}
191
192static void put_entry(struct my_data *entry)
193{
1373bed3 194 mutex_lock(&mutex);
5c11c520
CM
195 if (kref_put(&entry->refcount, release_entry)) {
196 list_del(&entry->link);
1373bed3 197 mutex_unlock(&mutex);
5c11c520
CM
198 kfree(entry);
199 } else
1373bed3 200 mutex_unlock(&mutex);
5c11c520
CM
201}
202
203This is really more useful if you have to call other routines as part
204of the free operations that could take a long time or might claim the
205same lock. Note that doing everything in the release routine is still
206preferred as it is a little neater.
207
208
209Corey Minyard <minyard@acm.org>
210
6f31e422
GKH
211A lot of this was lifted from Greg Kroah-Hartman's 2004 OLS paper and
212presentation on krefs, which can be found at:
213 http://www.kroah.com/linux/talks/ols_2004_kref_paper/Reprint-Kroah-Hartman-OLS2004.pdf
214and:
215 http://www.kroah.com/linux/talks/ols_2004_kref_talk/
216
a82b8db0
TH
217
218The above example could also be optimized using kref_get_unless_zero() in
219the following way:
220
221static struct my_data *get_entry()
222{
223 struct my_data *entry = NULL;
224 mutex_lock(&mutex);
225 if (!list_empty(&q)) {
226 entry = container_of(q.next, struct my_data, link);
227 if (!kref_get_unless_zero(&entry->refcount))
228 entry = NULL;
229 }
230 mutex_unlock(&mutex);
231 return entry;
232}
233
234static void release_entry(struct kref *ref)
235{
236 struct my_data *entry = container_of(ref, struct my_data, refcount);
237
238 mutex_lock(&mutex);
239 list_del(&entry->link);
240 mutex_unlock(&mutex);
241 kfree(entry);
242}
243
244static void put_entry(struct my_data *entry)
245{
246 kref_put(&entry->refcount, release_entry);
247}
248
249Which is useful to remove the mutex lock around kref_put() in put_entry(), but
250it's important that kref_get_unless_zero is enclosed in the same critical
251section that finds the entry in the lookup table,
252otherwise kref_get_unless_zero may reference already freed memory.
253Note that it is illegal to use kref_get_unless_zero without checking its
254return value. If you are sure (by already having a valid pointer) that
255kref_get_unless_zero() will return true, then use kref_get() instead.
256
257The function kref_get_unless_zero also makes it possible to use rcu
258locking for lookups in the above example:
259
260struct my_data
261{
262 struct rcu_head rhead;
263 .
264 struct kref refcount;
265 .
266 .
267};
268
269static struct my_data *get_entry_rcu()
270{
271 struct my_data *entry = NULL;
272 rcu_read_lock();
273 if (!list_empty(&q)) {
274 entry = container_of(q.next, struct my_data, link);
275 if (!kref_get_unless_zero(&entry->refcount))
276 entry = NULL;
277 }
278 rcu_read_unlock();
279 return entry;
280}
281
282static void release_entry_rcu(struct kref *ref)
283{
284 struct my_data *entry = container_of(ref, struct my_data, refcount);
285
286 mutex_lock(&mutex);
287 list_del_rcu(&entry->link);
288 mutex_unlock(&mutex);
289 kfree_rcu(entry, rhead);
290}
291
292static void put_entry(struct my_data *entry)
293{
294 kref_put(&entry->refcount, release_entry_rcu);
295}
296
297But note that the struct kref member needs to remain in valid memory for a
298rcu grace period after release_entry_rcu was called. That can be accomplished
299by using kfree_rcu(entry, rhead) as done above, or by calling synchronize_rcu()
300before using kfree, but note that synchronize_rcu() may sleep for a
301substantial amount of time.
302
303
304Thomas Hellstrom <thellstrom@vmware.com>