About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / kref.txt




Custom Search

Based on kernel version 3.4. Page generated on 2012-05-21 22:07 EST.

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/
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog
Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.