From: Ben Pfaff <blp@cs.stanford.edu>
Date: Sat, 8 Nov 2008 01:23:09 +0000 (-0800)
Subject: Correct comment describing list_remove() behavior.
X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?p=pintos-anon;a=commitdiff_plain;h=f017336df083c40df490f2a88e196b3df03ecbd1

Correct comment describing list_remove() behavior.

Thanks to Godmar for pointing out the problem.
---

diff --git a/src/lib/kernel/list.c b/src/lib/kernel/list.c
index e9993cb..316d9ef 100644
--- a/src/lib/kernel/list.c
+++ b/src/lib/kernel/list.c
@@ -222,21 +222,13 @@ 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.
 
-   It's not safe to treat ELEM as an element in a list after
-   removing it.  In particular, using list_next() or list_prev()
-   on ELEM after removal yields undefined behavior.  This means
-   that a naive loop to remove the elements in a list will fail:
+   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!
 
-   ** DON'T DO THIS **
-   for (e = list_begin (&list); e != list_end (&list); e = list_next (e))
-     {
-       ...do something with e...
-       list_remove (e);
-     }
-   ** DON'T DO THIS **
-
-   Here is one correct way to iterate and remove elements from a
-   list:
+   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))
      {