Root/Documentation/kref.txt

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_q_entry, 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

Archive Download this file



interactive