Back to home page

LXR

 
 

    


0001 
0002 krefs allow you to add reference counters to your objects.  If you
0003 have objects that are used in multiple places and passed around, and
0004 you don't have refcounts, your code is almost certainly broken.  If
0005 you want refcounts, krefs are the way to go.
0006 
0007 To use a kref, add one to your data structures like:
0008 
0009 struct my_data
0010 {
0011         .
0012         .
0013         struct kref refcount;
0014         .
0015         .
0016 };
0017 
0018 The kref can occur anywhere within the data structure.
0019 
0020 You must initialize the kref after you allocate it.  To do this, call
0021 kref_init as so:
0022 
0023      struct my_data *data;
0024 
0025      data = kmalloc(sizeof(*data), GFP_KERNEL);
0026      if (!data)
0027             return -ENOMEM;
0028      kref_init(&data->refcount);
0029 
0030 This sets the refcount in the kref to 1.
0031 
0032 Once you have an initialized kref, you must follow the following
0033 rules:
0034 
0035 1) If you make a non-temporary copy of a pointer, especially if
0036    it can be passed to another thread of execution, you must
0037    increment the refcount with kref_get() before passing it off:
0038        kref_get(&data->refcount);
0039    If you already have a valid pointer to a kref-ed structure (the
0040    refcount cannot go to zero) you may do this without a lock.
0041 
0042 2) When you are done with a pointer, you must call kref_put():
0043        kref_put(&data->refcount, data_release);
0044    If this is the last reference to the pointer, the release
0045    routine will be called.  If the code never tries to get
0046    a valid pointer to a kref-ed structure without already
0047    holding a valid pointer, it is safe to do this without
0048    a lock.
0049 
0050 3) If the code attempts to gain a reference to a kref-ed structure
0051    without already holding a valid pointer, it must serialize access
0052    where a kref_put() cannot occur during the kref_get(), and the
0053    structure must remain valid during the kref_get().
0054 
0055 For example, if you allocate some data and then pass it to another
0056 thread to process:
0057 
0058 void data_release(struct kref *ref)
0059 {
0060         struct my_data *data = container_of(ref, struct my_data, refcount);
0061         kfree(data);
0062 }
0063 
0064 void more_data_handling(void *cb_data)
0065 {
0066         struct my_data *data = cb_data;
0067         .
0068         . do stuff with data here
0069         .
0070         kref_put(&data->refcount, data_release);
0071 }
0072 
0073 int my_data_handler(void)
0074 {
0075         int rv = 0;
0076         struct my_data *data;
0077         struct task_struct *task;
0078         data = kmalloc(sizeof(*data), GFP_KERNEL);
0079         if (!data)
0080                 return -ENOMEM;
0081         kref_init(&data->refcount);
0082 
0083         kref_get(&data->refcount);
0084         task = kthread_run(more_data_handling, data, "more_data_handling");
0085         if (task == ERR_PTR(-ENOMEM)) {
0086                 rv = -ENOMEM;
0087                 goto out;
0088         }
0089 
0090         .
0091         . do stuff with data here
0092         .
0093  out:
0094         kref_put(&data->refcount, data_release);
0095         return rv;
0096 }
0097 
0098 This way, it doesn't matter what order the two threads handle the
0099 data, the kref_put() handles knowing when the data is not referenced
0100 any more and releasing it.  The kref_get() does not require a lock,
0101 since we already have a valid pointer that we own a refcount for.  The
0102 put needs no lock because nothing tries to get the data without
0103 already holding a pointer.
0104 
0105 Note that the "before" in rule 1 is very important.  You should never
0106 do something like:
0107 
0108         task = kthread_run(more_data_handling, data, "more_data_handling");
0109         if (task == ERR_PTR(-ENOMEM)) {
0110                 rv = -ENOMEM;
0111                 goto out;
0112         } else
0113                 /* BAD BAD BAD - get is after the handoff */
0114                 kref_get(&data->refcount);
0115 
0116 Don't assume you know what you are doing and use the above construct.
0117 First of all, you may not know what you are doing.  Second, you may
0118 know what you are doing (there are some situations where locking is
0119 involved where the above may be legal) but someone else who doesn't
0120 know what they are doing may change the code or copy the code.  It's
0121 bad style.  Don't do it.
0122 
0123 There are some situations where you can optimize the gets and puts.
0124 For instance, if you are done with an object and enqueuing it for
0125 something else or passing it off to something else, there is no reason
0126 to do a get then a put:
0127 
0128         /* Silly extra get and put */
0129         kref_get(&obj->ref);
0130         enqueue(obj);
0131         kref_put(&obj->ref, obj_cleanup);
0132 
0133 Just do the enqueue.  A comment about this is always welcome:
0134 
0135         enqueue(obj);
0136         /* We are done with obj, so we pass our refcount off
0137            to the queue.  DON'T TOUCH obj AFTER HERE! */
0138 
0139 The last rule (rule 3) is the nastiest one to handle.  Say, for
0140 instance, you have a list of items that are each kref-ed, and you wish
0141 to get the first one.  You can't just pull the first item off the list
0142 and kref_get() it.  That violates rule 3 because you are not already
0143 holding a valid pointer.  You must add a mutex (or some other lock).
0144 For instance:
0145 
0146 static DEFINE_MUTEX(mutex);
0147 static LIST_HEAD(q);
0148 struct my_data
0149 {
0150         struct kref      refcount;
0151         struct list_head link;
0152 };
0153 
0154 static struct my_data *get_entry()
0155 {
0156         struct my_data *entry = NULL;
0157         mutex_lock(&mutex);
0158         if (!list_empty(&q)) {
0159                 entry = container_of(q.next, struct my_data, link);
0160                 kref_get(&entry->refcount);
0161         }
0162         mutex_unlock(&mutex);
0163         return entry;
0164 }
0165 
0166 static void release_entry(struct kref *ref)
0167 {
0168         struct my_data *entry = container_of(ref, struct my_data, refcount);
0169 
0170         list_del(&entry->link);
0171         kfree(entry);
0172 }
0173 
0174 static void put_entry(struct my_data *entry)
0175 {
0176         mutex_lock(&mutex);
0177         kref_put(&entry->refcount, release_entry);
0178         mutex_unlock(&mutex);
0179 }
0180 
0181 The kref_put() return value is useful if you do not want to hold the
0182 lock during the whole release operation.  Say you didn't want to call
0183 kfree() with the lock held in the example above (since it is kind of
0184 pointless to do so).  You could use kref_put() as follows:
0185 
0186 static void release_entry(struct kref *ref)
0187 {
0188         /* All work is done after the return from kref_put(). */
0189 }
0190 
0191 static void put_entry(struct my_data *entry)
0192 {
0193         mutex_lock(&mutex);
0194         if (kref_put(&entry->refcount, release_entry)) {
0195                 list_del(&entry->link);
0196                 mutex_unlock(&mutex);
0197                 kfree(entry);
0198         } else
0199                 mutex_unlock(&mutex);
0200 }
0201 
0202 This is really more useful if you have to call other routines as part
0203 of the free operations that could take a long time or might claim the
0204 same lock.  Note that doing everything in the release routine is still
0205 preferred as it is a little neater.
0206 
0207 
0208 Corey Minyard <minyard@acm.org>
0209 
0210 A lot of this was lifted from Greg Kroah-Hartman's 2004 OLS paper and
0211 presentation on krefs, which can be found at:
0212   http://www.kroah.com/linux/talks/ols_2004_kref_paper/Reprint-Kroah-Hartman-OLS2004.pdf
0213 and:
0214   http://www.kroah.com/linux/talks/ols_2004_kref_talk/
0215 
0216 
0217 The above example could also be optimized using kref_get_unless_zero() in
0218 the following way:
0219 
0220 static struct my_data *get_entry()
0221 {
0222         struct my_data *entry = NULL;
0223         mutex_lock(&mutex);
0224         if (!list_empty(&q)) {
0225                 entry = container_of(q.next, struct my_data, link);
0226                 if (!kref_get_unless_zero(&entry->refcount))
0227                         entry = NULL;
0228         }
0229         mutex_unlock(&mutex);
0230         return entry;
0231 }
0232 
0233 static void release_entry(struct kref *ref)
0234 {
0235         struct my_data *entry = container_of(ref, struct my_data, refcount);
0236 
0237         mutex_lock(&mutex);
0238         list_del(&entry->link);
0239         mutex_unlock(&mutex);
0240         kfree(entry);
0241 }
0242 
0243 static void put_entry(struct my_data *entry)
0244 {
0245         kref_put(&entry->refcount, release_entry);
0246 }
0247 
0248 Which is useful to remove the mutex lock around kref_put() in put_entry(), but
0249 it's important that kref_get_unless_zero is enclosed in the same critical
0250 section that finds the entry in the lookup table,
0251 otherwise kref_get_unless_zero may reference already freed memory.
0252 Note that it is illegal to use kref_get_unless_zero without checking its
0253 return value. If you are sure (by already having a valid pointer) that
0254 kref_get_unless_zero() will return true, then use kref_get() instead.
0255 
0256 The function kref_get_unless_zero also makes it possible to use rcu
0257 locking for lookups in the above example:
0258 
0259 struct my_data
0260 {
0261         struct rcu_head rhead;
0262         .
0263         struct kref refcount;
0264         .
0265         .
0266 };
0267 
0268 static struct my_data *get_entry_rcu()
0269 {
0270         struct my_data *entry = NULL;
0271         rcu_read_lock();
0272         if (!list_empty(&q)) {
0273                 entry = container_of(q.next, struct my_data, link);
0274                 if (!kref_get_unless_zero(&entry->refcount))
0275                         entry = NULL;
0276         }
0277         rcu_read_unlock();
0278         return entry;
0279 }
0280 
0281 static void release_entry_rcu(struct kref *ref)
0282 {
0283         struct my_data *entry = container_of(ref, struct my_data, refcount);
0284 
0285         mutex_lock(&mutex);
0286         list_del_rcu(&entry->link);
0287         mutex_unlock(&mutex);
0288         kfree_rcu(entry, rhead);
0289 }
0290 
0291 static void put_entry(struct my_data *entry)
0292 {
0293         kref_put(&entry->refcount, release_entry_rcu);
0294 }
0295 
0296 But note that the struct kref member needs to remain in valid memory for a
0297 rcu grace period after release_entry_rcu was called. That can be accomplished
0298 by using kfree_rcu(entry, rhead) as done above, or by calling synchronize_rcu()
0299 before using kfree, but note that synchronize_rcu() may sleep for a
0300 substantial amount of time.
0301 
0302 
0303 Thomas Hellstrom <thellstrom@vmware.com>