linux/Documentation/kref.txt
<<
>>
Prefs
   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
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.