X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;ds=sidebyside;f=src%2Flib%2Fkernel%2Flist.c;h=316d9ef64cd166e6422117f9c914efde5c5fdfde;hb=94d17ee9287aec1c4c9ee37ca02615e8293a5f3a;hp=0b37f33dc9f70b7ec66952f77100b96c0f7585bc;hpb=615bf3b3d2a8573ed6fb9ddc0055745e163ac999;p=pintos-anon

diff --git a/src/lib/kernel/list.c b/src/lib/kernel/list.c
index 0b37f33..316d9ef 100644
--- 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)
 {