[PATCH] list_empty_careful() documentation.

From: Ingo Molnar <mingo@elte.hu>

I'd also suggest the following patch below, to clarify the use of
unsynchronized list_empty().  list_empty_careful() can only be safe in the
very specific case of "one-shot" list entries which might be removed by
another CPU.  (but nothing else can happen to them and this is their only
final state.) list_empty_careful() is otherwise completely unsynchronized
on both the compiler and CPU level and is not 'SMP safe' in any way.

diff --git a/include/linux/list.h b/include/linux/list.h
index 0835011b0ffbdcc036c19df74d3ee84b7334f320..9a5df31af22e678f258c8ca0a3e5c8701377bd9e 100644 (file)
--- a/include/linux/list.h
+++ b/include/linux/list.h
@@ -212,6 +212,12 @@ static inline int list_empty(const struct list_head *head)
  * list_empty_careful - tests whether a list is
  * empty _and_ checks that no other CPU might be
  * in the process of still modifying either member
+ *
+ * NOTE: using list_empty_careful() without synchronization
+ * can only be safe if the only activity that can happen
+ * to the list entry is list_del_init(). Eg. it cannot be used
+ * if another CPU could re-list_add() it.
+ *
  * @head: the list to test.
  */
 static inline int list_empty_careful(const struct list_head *head)