p71924506
/
linux_old1
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

rculist: Unify documentation about missing list_empty_rcu() 

We have two separate sections that talk about why list_empty_rcu()
is not needed, so this commit consolidates them.

Signed-off-by: Julian Wiedmann <jwi@linux.ibm.com>
[ paulmck: The usual wordsmithing. ]
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
This commit is contained in:
Julian Wiedmann 2021-05-21 12:08:29 +02:00 committed by Paul E. McKenney
parent 5fcb3a5f04
commit 751b1710eb
1 changed files with 16 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
include/linux/rculist.h
View File

@ -10,15 +10,6 @@
#include <linux/list.h> #include <linux/list.h>
#include <linux/rcupdate.h> #include <linux/rcupdate.h>
/*
* Why is there no list_empty_rcu()? Because list_empty() serves this
* purpose. The list_empty() function fetches the RCU-protected pointer
* and compares it to the address of the list head, but neither dereferences
* this pointer itself nor provides this pointer to the caller. Therefore,
* it is not necessary to use rcu_dereference(), so that list_empty() can
* be used anywhere you would want to use a list_empty_rcu().
*/
/* /*
* INIT_LIST_HEAD_RCU - Initialize a list_head visible to RCU readers * INIT_LIST_HEAD_RCU - Initialize a list_head visible to RCU readers
* @list: list to be initialized * @list: list to be initialized
@ -318,21 +309,29 @@ static inline void list_splice_tail_init_rcu(struct list_head *list,
/* /*
* Where are list_empty_rcu() and list_first_entry_rcu()? * Where are list_empty_rcu() and list_first_entry_rcu()?
* *
* Implementing those functions following their counterparts list_empty() and * They do not exist because they would lead to subtle race conditions:
* list_first_entry() is not advisable because they lead to subtle race
* conditions as the following snippet shows:
* *
* if (!list_empty_rcu(mylist)) { * if (!list_empty_rcu(mylist)) {
* struct foo *bar = list_first_entry_rcu(mylist, struct foo, list_member); * struct foo *bar = list_first_entry_rcu(mylist, struct foo, list_member);
* do_something(bar); * do_something(bar);
* } * }
* *
* The list may not be empty when list_empty_rcu checks it, but it may be when * The list might be non-empty when list_empty_rcu() checks it, but it
* list_first_entry_rcu rereads the ->next pointer. * might have become empty by the time that list_first_entry_rcu() rereads
* the ->next pointer, which would result in a SEGV.
* *
* Rereading the ->next pointer is not a problem for list_empty() and * When not using RCU, it is OK for list_first_entry() to re-read that
* list_first_entry() because they would be protected by a lock that blocks * pointer because both functions should be protected by some lock that
* writers. * blocks writers.
*
* When using RCU, list_empty() uses READ_ONCE() to fetch the
* RCU-protected ->next pointer and then compares it to the address of the
* list head. However, it neither dereferences this pointer nor provides
* this pointer to its caller. Thus, READ_ONCE() suffices (that is,
* rcu_dereference() is not needed), which means that list_empty() can be
* used anywhere you would want to use list_empty_rcu(). Just don't
* expect anything useful to happen if you do a subsequent lockless
* call to list_first_entry_rcu()!!!
* *
* See list_first_or_null_rcu for an alternative. * See list_first_or_null_rcu for an alternative.
*/ */