[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.

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)