[PATCH 09/10] lib/list_sort: improve list_sort() function documentation

[don.mullis@gmail.com]

[-- Attachment #1: lib_list_sort_-Improve-list_sort__-function-comment-3.patch --]
[-- Type: text/plain, Size: 1306 bytes --]

From: Artem Bityutskiy <Artem.Bityutskiy@nokia.com>

Remind users that degenerate callbacks to cmp(a, b), with a==b, are
normal.

Signed-off-by: Artem Bityutskiy <Artem.Bityutskiy@nokia.com>
Signed-off-by: Don Mullis <don.mullis@gmail.com>
---
 lib/list_sort.c |    7 +++++++
 1 file changed, 7 insertions(+)

Index: linux-next/lib/list_sort.c
===================================================================
--- linux-next.orig/lib/list_sort.c	2010-08-23 22:51:19.761177595 -0700
+++ linux-next/lib/list_sort.c	2010-08-23 23:01:55.242052357 -0700
@@ -93,6 +93,13 @@ static void merge_and_restore_back_links
  * should sort before @b, and a positive value if @a should sort after
  * @b. If @a and @b are equivalent, and their original relative
  * ordering is to be preserved, @cmp must return 0.
+ *
+ * This function may be used in atomic context, and may be
+ * long-running, in which case @cmp must take care of calling
+ * 'cond_resched()' when needed. And 'list_sort()' will sometimes call
+ * @cmp with @a == @b, just to let the user call 'cond_resched()'.
+ * This "degenerate" callback comes from a loop that requires no
+ * actual comparison results, but nevertheless runs in O(n) time.
  */
 void list_sort(void *priv, struct list_head *head,
 		int (*cmp)(void *priv, struct list_head *a,