Documentation/kref.txt

   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
 217 The above example could also be optimized using kref_get_unless_zero() in
 218 the following way:
 219
 220 static 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
 233 static 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
 243 static void put_entry(struct my_data *entry)
 244 {
 245         kref_put(&entry->refcount, release_entry);
 246 }
 247
 248 Which is useful to remove the mutex lock around kref_put() in put_entry(), but
 249 it's important that kref_get_unless_zero is enclosed in the same critical
 250 section that finds the entry in the lookup table,
 251 otherwise kref_get_unless_zero may reference already freed memory.
 252 Note that it is illegal to use kref_get_unless_zero without checking its
 253 return value. If you are sure (by already having a valid pointer) that
 254 kref_get_unless_zero() will return true, then use kref_get() instead.
 255
 256 The function kref_get_unless_zero also makes it possible to use rcu
 257 locking for lookups in the above example:
 258
 259 struct my_data
 260 {
 261         struct rcu_head rhead;
 262         .
 263         struct kref refcount;
 264         .
 265         .
 266 };
 267
 268 static 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
 281 static 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
 291 static void put_entry(struct my_data *entry)
 292 {
 293         kref_put(&entry->refcount, release_entry_rcu);
 294 }
 295
 296 But note that the struct kref member needs to remain in valid memory for a
 297 rcu grace period after release_entry_rcu was called. That can be accomplished
 298 by using kfree_rcu(entry, rhead) as done above, or by calling synchronize_rcu()
 299 before using kfree, but note that synchronize_rcu() may sleep for a
 300 substantial amount of time.
 301
 302
 303 Thomas Hellstrom <thellstrom@vmware.com>