mirror of
https://github.com/tbsdtv/linux_media.git
synced 2025-07-23 12:43:29 +02:00
doc: Update and wordsmith rculist_nulls.rst
Do some wordsmithing and breaking up of RCU readers. Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
This commit is contained in:
@@ -14,19 +14,19 @@ Using 'nulls'
|
|||||||
=============
|
=============
|
||||||
|
|
||||||
Using special makers (called 'nulls') is a convenient way
|
Using special makers (called 'nulls') is a convenient way
|
||||||
to solve following problem :
|
to solve following problem.
|
||||||
|
|
||||||
A typical RCU linked list managing objects which are
|
Without 'nulls', a typical RCU linked list managing objects which are
|
||||||
allocated with SLAB_TYPESAFE_BY_RCU kmem_cache can
|
allocated with SLAB_TYPESAFE_BY_RCU kmem_cache can use the following
|
||||||
use following algos :
|
algorithms:
|
||||||
|
|
||||||
1) Lookup algo
|
1) Lookup algorithm
|
||||||
--------------
|
-------------------
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
rcu_read_lock()
|
|
||||||
begin:
|
begin:
|
||||||
|
rcu_read_lock()
|
||||||
obj = lockless_lookup(key);
|
obj = lockless_lookup(key);
|
||||||
if (obj) {
|
if (obj) {
|
||||||
if (!try_get_ref(obj)) // might fail for free objects
|
if (!try_get_ref(obj)) // might fail for free objects
|
||||||
@@ -38,6 +38,7 @@ use following algos :
|
|||||||
*/
|
*/
|
||||||
if (obj->key != key) { // not the object we expected
|
if (obj->key != key) { // not the object we expected
|
||||||
put_ref(obj);
|
put_ref(obj);
|
||||||
|
rcu_read_unlock();
|
||||||
goto begin;
|
goto begin;
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -52,9 +53,9 @@ but a version with an additional memory barrier (smp_rmb())
|
|||||||
{
|
{
|
||||||
struct hlist_node *node, *next;
|
struct hlist_node *node, *next;
|
||||||
for (pos = rcu_dereference((head)->first);
|
for (pos = rcu_dereference((head)->first);
|
||||||
pos && ({ next = pos->next; smp_rmb(); prefetch(next); 1; }) &&
|
pos && ({ next = pos->next; smp_rmb(); prefetch(next); 1; }) &&
|
||||||
({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; });
|
({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; });
|
||||||
pos = rcu_dereference(next))
|
pos = rcu_dereference(next))
|
||||||
if (obj->key == key)
|
if (obj->key == key)
|
||||||
return obj;
|
return obj;
|
||||||
return NULL;
|
return NULL;
|
||||||
@@ -64,9 +65,9 @@ And note the traditional hlist_for_each_entry_rcu() misses this smp_rmb()::
|
|||||||
|
|
||||||
struct hlist_node *node;
|
struct hlist_node *node;
|
||||||
for (pos = rcu_dereference((head)->first);
|
for (pos = rcu_dereference((head)->first);
|
||||||
pos && ({ prefetch(pos->next); 1; }) &&
|
pos && ({ prefetch(pos->next); 1; }) &&
|
||||||
({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; });
|
({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; });
|
||||||
pos = rcu_dereference(pos->next))
|
pos = rcu_dereference(pos->next))
|
||||||
if (obj->key == key)
|
if (obj->key == key)
|
||||||
return obj;
|
return obj;
|
||||||
return NULL;
|
return NULL;
|
||||||
@@ -82,36 +83,32 @@ Quoting Corey Minyard::
|
|||||||
solved by pre-fetching the "next" field (with proper barriers) before
|
solved by pre-fetching the "next" field (with proper barriers) before
|
||||||
checking the key."
|
checking the key."
|
||||||
|
|
||||||
2) Insert algo
|
2) Insertion algorithm
|
||||||
--------------
|
----------------------
|
||||||
|
|
||||||
We need to make sure a reader cannot read the new 'obj->obj_next' value
|
We need to make sure a reader cannot read the new 'obj->obj_next' value
|
||||||
and previous value of 'obj->key'. Or else, an item could be deleted
|
and previous value of 'obj->key'. Otherwise, an item could be deleted
|
||||||
from a chain, and inserted into another chain. If new chain was empty
|
from a chain, and inserted into another chain. If new chain was empty
|
||||||
before the move, 'next' pointer is NULL, and lockless reader can
|
before the move, 'next' pointer is NULL, and lockless reader can not
|
||||||
not detect it missed following items in original chain.
|
detect the fact that it missed following items in original chain.
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
/*
|
/*
|
||||||
* Please note that new inserts are done at the head of list,
|
* Please note that new inserts are done at the head of list,
|
||||||
* not in the middle or end.
|
* not in the middle or end.
|
||||||
*/
|
*/
|
||||||
obj = kmem_cache_alloc(...);
|
obj = kmem_cache_alloc(...);
|
||||||
lock_chain(); // typically a spin_lock()
|
lock_chain(); // typically a spin_lock()
|
||||||
obj->key = key;
|
obj->key = key;
|
||||||
/*
|
atomic_set_release(&obj->refcnt, 1); // key before refcnt
|
||||||
* we need to make sure obj->key is updated before obj->next
|
|
||||||
* or obj->refcnt
|
|
||||||
*/
|
|
||||||
smp_wmb();
|
|
||||||
atomic_set(&obj->refcnt, 1);
|
|
||||||
hlist_add_head_rcu(&obj->obj_node, list);
|
hlist_add_head_rcu(&obj->obj_node, list);
|
||||||
unlock_chain(); // typically a spin_unlock()
|
unlock_chain(); // typically a spin_unlock()
|
||||||
|
|
||||||
|
|
||||||
3) Remove algo
|
3) Removal algorithm
|
||||||
--------------
|
--------------------
|
||||||
|
|
||||||
Nothing special here, we can use a standard RCU hlist deletion.
|
Nothing special here, we can use a standard RCU hlist deletion.
|
||||||
But thanks to SLAB_TYPESAFE_BY_RCU, beware a deleted object can be reused
|
But thanks to SLAB_TYPESAFE_BY_RCU, beware a deleted object can be reused
|
||||||
very very fast (before the end of RCU grace period)
|
very very fast (before the end of RCU grace period)
|
||||||
@@ -133,7 +130,7 @@ Avoiding extra smp_rmb()
|
|||||||
========================
|
========================
|
||||||
|
|
||||||
With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup()
|
With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup()
|
||||||
and extra smp_wmb() in insert function.
|
and extra _release() in insert function.
|
||||||
|
|
||||||
For example, if we choose to store the slot number as the 'nulls'
|
For example, if we choose to store the slot number as the 'nulls'
|
||||||
end-of-list marker for each slot of the hash table, we can detect
|
end-of-list marker for each slot of the hash table, we can detect
|
||||||
@@ -142,59 +139,61 @@ to another chain) checking the final 'nulls' value if
|
|||||||
the lookup met the end of chain. If final 'nulls' value
|
the lookup met the end of chain. If final 'nulls' value
|
||||||
is not the slot number, then we must restart the lookup at
|
is not the slot number, then we must restart the lookup at
|
||||||
the beginning. If the object was moved to the same chain,
|
the beginning. If the object was moved to the same chain,
|
||||||
then the reader doesn't care : It might eventually
|
then the reader doesn't care: It might occasionally
|
||||||
scan the list again without harm.
|
scan the list again without harm.
|
||||||
|
|
||||||
|
|
||||||
1) lookup algo
|
1) lookup algorithm
|
||||||
--------------
|
-------------------
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
head = &table[slot];
|
head = &table[slot];
|
||||||
rcu_read_lock();
|
|
||||||
begin:
|
begin:
|
||||||
|
rcu_read_lock();
|
||||||
hlist_nulls_for_each_entry_rcu(obj, node, head, member) {
|
hlist_nulls_for_each_entry_rcu(obj, node, head, member) {
|
||||||
if (obj->key == key) {
|
if (obj->key == key) {
|
||||||
if (!try_get_ref(obj)) // might fail for free objects
|
if (!try_get_ref(obj)) { // might fail for free objects
|
||||||
goto begin;
|
rcu_read_unlock();
|
||||||
if (obj->key != key) { // not the object we expected
|
|
||||||
put_ref(obj);
|
|
||||||
goto begin;
|
goto begin;
|
||||||
}
|
}
|
||||||
goto out;
|
if (obj->key != key) { // not the object we expected
|
||||||
|
put_ref(obj);
|
||||||
|
rcu_read_unlock();
|
||||||
|
goto begin;
|
||||||
|
}
|
||||||
|
goto out;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// If the nulls value we got at the end of this lookup is
|
||||||
|
// not the expected one, we must restart lookup.
|
||||||
|
// We probably met an item that was moved to another chain.
|
||||||
|
if (get_nulls_value(node) != slot) {
|
||||||
|
put_ref(obj);
|
||||||
|
rcu_read_unlock();
|
||||||
|
goto begin;
|
||||||
}
|
}
|
||||||
/*
|
|
||||||
* if the nulls value we got at the end of this lookup is
|
|
||||||
* not the expected one, we must restart lookup.
|
|
||||||
* We probably met an item that was moved to another chain.
|
|
||||||
*/
|
|
||||||
if (get_nulls_value(node) != slot)
|
|
||||||
goto begin;
|
|
||||||
obj = NULL;
|
obj = NULL;
|
||||||
|
|
||||||
out:
|
out:
|
||||||
rcu_read_unlock();
|
rcu_read_unlock();
|
||||||
|
|
||||||
2) Insert function
|
2) Insert algorithm
|
||||||
------------------
|
-------------------
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
/*
|
/*
|
||||||
* Please note that new inserts are done at the head of list,
|
* Please note that new inserts are done at the head of list,
|
||||||
* not in the middle or end.
|
* not in the middle or end.
|
||||||
*/
|
*/
|
||||||
obj = kmem_cache_alloc(cachep);
|
obj = kmem_cache_alloc(cachep);
|
||||||
lock_chain(); // typically a spin_lock()
|
lock_chain(); // typically a spin_lock()
|
||||||
obj->key = key;
|
obj->key = key;
|
||||||
|
atomic_set_release(&obj->refcnt, 1); // key before refcnt
|
||||||
/*
|
/*
|
||||||
* changes to obj->key must be visible before refcnt one
|
* insert obj in RCU way (readers might be traversing chain)
|
||||||
*/
|
*/
|
||||||
smp_wmb();
|
|
||||||
atomic_set(&obj->refcnt, 1);
|
|
||||||
/*
|
|
||||||
* insert obj in RCU way (readers might be traversing chain)
|
|
||||||
*/
|
|
||||||
hlist_nulls_add_head_rcu(&obj->obj_node, list);
|
hlist_nulls_add_head_rcu(&obj->obj_node, list);
|
||||||
unlock_chain(); // typically a spin_unlock()
|
unlock_chain(); // typically a spin_unlock()
|
||||||
|
Reference in New Issue
Block a user