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