Root/
Source at commit be977234bfb4a6dca8a39e7c52165e4cd536ad71 created 12 years 9 months ago. By Lars-Peter Clausen, jz4740: Fix compile error | |
---|---|
1 | |
2 | krefs allow you to add reference counters to your objects. If you |
3 | have objects that are used in multiple places and passed around, and |
4 | you don't have refcounts, your code is almost certainly broken. If |
5 | you want refcounts, krefs are the way to go. |
6 | |
7 | To use a kref, add one to your data structures like: |
8 | |
9 | struct my_data |
10 | { |
11 | . |
12 | . |
13 | struct kref refcount; |
14 | . |
15 | . |
16 | }; |
17 | |
18 | The kref can occur anywhere within the data structure. |
19 | |
20 | You must initialize the kref after you allocate it. To do this, call |
21 | kref_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 | |
30 | This sets the refcount in the kref to 1. |
31 | |
32 | Once you have an initialized kref, you must follow the following |
33 | rules: |
34 | |
35 | 1) 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 | |
42 | 2) 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 | |
50 | 3) 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 | |
55 | For example, if you allocate some data and then pass it to another |
56 | thread to process: |
57 | |
58 | void data_release(struct kref *ref) |
59 | { |
60 | struct my_data *data = container_of(ref, struct my_data, refcount); |
61 | kfree(data); |
62 | } |
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 | |
73 | int 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 | |
98 | This way, it doesn't matter what order the two threads handle the |
99 | data, the kref_put() handles knowing when the data is not referenced |
100 | any more and releasing it. The kref_get() does not require a lock, |
101 | since we already have a valid pointer that we own a refcount for. The |
102 | put needs no lock because nothing tries to get the data without |
103 | already holding a pointer. |
104 | |
105 | Note that the "before" in rule 1 is very important. You should never |
106 | do 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 | |
116 | Don't assume you know what you are doing and use the above construct. |
117 | First of all, you may not know what you are doing. Second, you may |
118 | know what you are doing (there are some situations where locking is |
119 | involved where the above may be legal) but someone else who doesn't |
120 | know what they are doing may change the code or copy the code. It's |
121 | bad style. Don't do it. |
122 | |
123 | There are some situations where you can optimize the gets and puts. |
124 | For instance, if you are done with an object and enqueuing it for |
125 | something else or passing it off to something else, there is no reason |
126 | to 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 | |
133 | Just 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 | |
139 | The last rule (rule 3) is the nastiest one to handle. Say, for |
140 | instance, you have a list of items that are each kref-ed, and you wish |
141 | to get the first one. You can't just pull the first item off the list |
142 | and kref_get() it. That violates rule 3 because you are not already |
143 | holding a valid pointer. You must add a mutex (or some other lock). |
144 | For instance: |
145 | |
146 | static DEFINE_MUTEX(mutex); |
147 | static LIST_HEAD(q); |
148 | struct my_data |
149 | { |
150 | struct kref refcount; |
151 | struct list_head link; |
152 | }; |
153 | |
154 | static 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 | |
166 | static 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 | |
174 | static 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 | |
181 | The kref_put() return value is useful if you do not want to hold the |
182 | lock during the whole release operation. Say you didn't want to call |
183 | kfree() with the lock held in the example above (since it is kind of |
184 | pointless to do so). You could use kref_put() as follows: |
185 | |
186 | static void release_entry(struct kref *ref) |
187 | { |
188 | /* All work is done after the return from kref_put(). */ |
189 | } |
190 | |
191 | static 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 | |
202 | This is really more useful if you have to call other routines as part |
203 | of the free operations that could take a long time or might claim the |
204 | same lock. Note that doing everything in the release routine is still |
205 | preferred as it is a little neater. |
206 | |
207 | |
208 | Corey Minyard <minyard@acm.org> |
209 | |
210 | A lot of this was lifted from Greg Kroah-Hartman's 2004 OLS paper and |
211 | presentation on krefs, which can be found at: |
212 | http://www.kroah.com/linux/talks/ols_2004_kref_paper/Reprint-Kroah-Hartman-OLS2004.pdf |
213 | and: |
214 | http://www.kroah.com/linux/talks/ols_2004_kref_talk/ |
215 | |
216 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9