aboutsummaryrefslogtreecommitdiff
path: root/Documentation/RCU/rcuref.txt
blob: a23fee66064df4ff6770e9be02f79af4a0397745 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
Refcounter framework for elements of lists/arrays protected by
RCU.

Refcounting on elements of  lists which are protected by traditional
reader/writer spinlocks or semaphores are straight forward as in:

1.					2.
add()					search_and_reference()
{					{
	alloc_object				read_lock(&list_lock);
	...					search_for_element
	atomic_set(&el->rc, 1);			atomic_inc(&el->rc);
	write_lock(&list_lock);			...
	add_element				read_unlock(&list_lock);
	...					...
	write_unlock(&list_lock);	}
}

3.					4.
release_referenced()			delete()
{					{
	...				write_lock(&list_lock);
	atomic_dec(&el->rc, relfunc)	...
	...				delete_element
}					write_unlock(&list_lock);
 					...
					if (atomic_dec_and_test(&el->rc))
						kfree(el);
					...
					}

If this list/array is made lock free using rcu as in changing the
write_lock in add() and delete() to spin_lock and changing read_lock
in search_and_reference to rcu_read_lock(), the rcuref_get in
search_and_reference could potentially hold reference to an element which
has already been deleted from the list/array.  rcuref_lf_get_rcu takes
care of this scenario. search_and_reference should look as;

1.					2.
add()					search_and_reference()
{					{
 	alloc_object				rcu_read_lock();
	...					search_for_element
	atomic_set(&el->rc, 1);			if (rcuref_inc_lf(&el->rc)) {
	write_lock(&list_lock);				rcu_read_unlock();
							return FAIL;
	add_element				}
	...					...
	write_unlock(&list_lock);		rcu_read_unlock();
}					}
3.					4.
release_referenced()			delete()
{					{
	...				write_lock(&list_lock);
	rcuref_dec(&el->rc, relfunc)	...
	...				delete_element
}					write_unlock(&list_lock);
 					...
					if (rcuref_dec_and_test(&el->rc))
						call_rcu(&el->head, el_free);
					...
					}

Sometimes, reference to the element need to be obtained in the
update (write) stream.  In such cases, rcuref_inc_lf might be an overkill
since the spinlock serialising list updates are held. rcuref_inc
is to be used in such cases.
For arches which do not have cmpxchg rcuref_inc_lf
api uses a hashed spinlock implementation and the same hashed spinlock
is acquired in all rcuref_xxx primitives to preserve atomicity.
Note: Use rcuref_inc api only if you need to use rcuref_inc_lf on the
refcounter atleast at one place.  Mixing rcuref_inc and atomic_xxx api
might lead to races. rcuref_inc_lf() must be used in lockfree
RCU critical sections only.