clarified specification for wait() system call

diff --git a/doc/userprog.texi b/doc/userprog.texi
index aaf75e2aead1b749589d786f55e7ef12555d592f..d3a70c810f7eb10e0b9823bb0fb82b3b962dbf59 100644 (file)
--- a/doc/userprog.texi
+++ b/doc/userprog.texi
@@ -622,14 +622,44 @@ You must use appropriate synchronization to ensure this.
 @end deftypefn
 
 @deftypefn {System Call} int wait (pid_t @var{pid})
-If process @var{pid} is still alive, waits until it dies.
-Then, returns the status that @var{pid} passed to @code{exit},
-or -1 if @var{pid}
-was terminated by the kernel (e.g.@: killed due to an exception).  If
-@var{pid} does not refer to a child of the
-calling thread, or if @code{wait} has already been successfully
-called for the given @var{pid}, returns -1 immediately, without
-waiting.
+Waits for a child process @var{pid} and retrieves the child's exit status.
+
+If @var{pid} is still alive, waits until it terminates.  Then, returns
+the status that @var{pid} passed to @code{exit}.  If @var{pid} did not
+call @code{exit()}, but was terminated by the kernel (e.g.@: killed
+due to an exception), @code{wait(pid)} must return -1.  It is perfectly
+legal for a parent process to wait for child processes that have already
+terminated by the time the parent calls @code{wait}, but the kernel must
+still allow the parent to retrieve its child's exit status, or learn
+that the child was terminated by the kernel.
+
+@code{wait} must fail and return -1 immediately if any of the
+following conditions is true:
+@itemize @bullet
+@item
+@var{pid} does not refer to a direct child of the calling process.
+@var{pid} is a direct child of the calling process if and
+only if the calling process received @var{pid} as a return value 
+from a successful call to @code{exec}.  
+
+Note that children are not inherited: if @var{A} spawns child @var{B}
+and @var{B} spawns child process @var{C}, then @var{A} cannot wait for
+@var{C}, even if @var{B} is dead.  A call to @code{wait(C)} by process
+@var{A} must fail.  Similarly, orphaned processes are not assigned to
+a new parent if their parent process exits before they do.
+
+@item
+The process that calls @code{wait} has already called @code{wait} on
+@var{pid}.  That is, a process may wait for any given child at most 
+once.
+@end itemize
+
+Processes may spawn any number of children, wait for them in any order, 
+and may even exit without having waited for some or all of their children.
+Your design should consider all the ways in which waits can occur.
+All of a process's resources, including its @struct{thread}, must be
+freed whether its parent ever waits for it or not, and regardless of
+whether the child exits before or after its parent.
 
 You must ensure that Pintos does not terminate until the initial
 process exits.  The supplied Pintos code tries to do this by calling
@@ -639,18 +669,6 @@ process exits.  The supplied Pintos code tries to do this by calling
 function and then implement the @code{wait} system call in terms of
 @func{process_wait}.
 
-All of a process's resources, including its @struct{thread}, must be
-freed whether its parent ever waits for it or not, and regardless of
-whether the child exits before or after its parent.
-
-Children are not inherited: if @var{A} has child @var{B} and
-@var{B} has child @var{C}, then @code{wait(C)} always returns immediately
-when called from @var{A}, even if @var{B} is dead.
-
-Consider all the ways a wait can occur: nested waits (@var{A} waits
-for @var{B}, then @var{B} waits for @var{C}), multiple waits (@var{A}
-waits for @var{B}, then @var{A} waits for @var{C}), and so on.
-
 Implementing this system call requires considerably more work than any
 of the rest.
 @end deftypefn