blob: 48ba715d5a633fb246855aca0595ce47ecb5e187 [file] [log] [blame]
minyard@acm.org5c11c522005-04-18 21:57:30 -07001
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 .
Satyam Sharmab7cc4a82007-05-11 19:07:14 +020070 kref_put(&data->refcount, data_release);
minyard@acm.org5c11c522005-04-18 21:57:30 -070071}
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;
minyard@acm.org5c11c522005-04-18 21:57:30 -070087 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
Daniel Walker1373bed2008-02-06 01:37:58 -0800143holding a valid pointer. You must add a mutex (or some other lock).
144For instance:
minyard@acm.org5c11c522005-04-18 21:57:30 -0700145
Daniel Walker1373bed2008-02-06 01:37:58 -0800146static DEFINE_MUTEX(mutex);
minyard@acm.org5c11c522005-04-18 21:57:30 -0700147static 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;
Daniel Walker1373bed2008-02-06 01:37:58 -0800157 mutex_lock(&mutex);
minyard@acm.org5c11c522005-04-18 21:57:30 -0700158 if (!list_empty(&q)) {
Javi Merinod5c97c12011-03-07 21:13:07 +0000159 entry = container_of(q.next, struct my_data, link);
minyard@acm.org5c11c522005-04-18 21:57:30 -0700160 kref_get(&entry->refcount);
161 }
Daniel Walker1373bed2008-02-06 01:37:58 -0800162 mutex_unlock(&mutex);
minyard@acm.org5c11c522005-04-18 21:57:30 -0700163 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{
Daniel Walker1373bed2008-02-06 01:37:58 -0800176 mutex_lock(&mutex);
minyard@acm.org5c11c522005-04-18 21:57:30 -0700177 kref_put(&entry->refcount, release_entry);
Daniel Walker1373bed2008-02-06 01:37:58 -0800178 mutex_unlock(&mutex);
minyard@acm.org5c11c522005-04-18 21:57:30 -0700179}
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{
Daniel Walker1373bed2008-02-06 01:37:58 -0800193 mutex_lock(&mutex);
minyard@acm.org5c11c522005-04-18 21:57:30 -0700194 if (kref_put(&entry->refcount, release_entry)) {
195 list_del(&entry->link);
Daniel Walker1373bed2008-02-06 01:37:58 -0800196 mutex_unlock(&mutex);
minyard@acm.org5c11c522005-04-18 21:57:30 -0700197 kfree(entry);
198 } else
Daniel Walker1373bed2008-02-06 01:37:58 -0800199 mutex_unlock(&mutex);
minyard@acm.org5c11c522005-04-18 21:57:30 -0700200}
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
gregkh@suse.de6f31e422005-04-18 21:57:30 -0700210A 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