Correct comment describing list_remove() behavior.

[pintos-anon] / src / lib / kernel / list.c

diff --git a/src/lib/kernel/list.c b/src/lib/kernel/list.c
index 0b37f33dc9f70b7ec66952f77100b96c0f7585bc..316d9ef64cd166e6422117f9c914efde5c5fdfde 100644 (file)
--- a/src/lib/kernel/list.c
+++ b/src/lib/kernel/list.c
@@ -220,7 +220,31 @@ list_push_back (struct list *list, struct list_elem *elem)
 }
 
 /* Removes ELEM from its list and returns the element that
-   followed it.  Undefined behavior if ELEM is not in a list.  */
+   followed it.  Undefined behavior if ELEM is not in a list.
+
+   A list element must be treated very carefully after removing
+   it from its list.  Calling list_next() or list_prev() on ELEM
+   will return the item that was previously before or after ELEM,
+   but, e.g., list_prev(list_next(ELEM)) is no longer ELEM!
+
+   The list_remove() return value provides a convenient way to
+   iterate and remove elements from a list:
+
+   for (e = list_begin (&list); e != list_end (&list); e = list_remove (e))
+     {
+       ...do something with e...
+     }
+
+   If you need to free() elements of the list then you need to be
+   more conservative.  Here's an alternate strategy that works
+   even in that case:
+
+   while (!list_empty (&list))
+     {
+       struct list_elem *e = list_pop_front (&list);
+       ...do something with e...
+     }
+*/
 struct list_elem *
 list_remove (struct list_elem *elem)
 {