Document throwing of UserInterrupt when ending Ctrl-C delegation

Author: robx

System/Process.hs

@@ -676,14 +676,16 @@ getCurrentPid =
 -- waitForProcess
 
 {- | Waits for the specified process to terminate, and returns its exit code.
+On Unix systems, may throw 'UserInterrupt' when using 'delegate_ctlc'.
 
 GHC Note: in order to call @waitForProcess@ without blocking all the
 other threads in the system, you must compile the program with
 @-threaded@.
 
 Note that it is safe to call @waitForProcess@ for the same process in multiple
 threads. When the process ends, threads blocking on this call will wake in
-FIFO order.
+FIFO order. When using 'delegate_ctlc' and the process is interrupted, only
+the first waiting thread will throw 'UserInterrupt'.
 
 (/Since: 1.2.0.0/) On Unix systems, a negative value @'ExitFailure' -/signum/@
 indicates that the child was terminated by signal @/signum/@.
@@ -710,6 +712,8 @@ waitForProcess ph@(ProcessHandle _ delegating_ctlc _) = lockWaitpid $ do
             OpenHandle ph'  -> do
               closePHANDLE ph'
               return (ClosedHandle e, (e, True))
+        -- endDelegateControlC after closing the handle, since it
+        -- may throw UserInterrupt
         when (was_open && delegating_ctlc) $
           endDelegateControlC e
         return e'
@@ -759,7 +763,8 @@ still running, 'Nothing' is returned.  If the process has exited, then
 @'Just' e@ is returned where @e@ is the exit code of the process.
 
 On Unix systems, see 'waitForProcess' for the meaning of exit codes
-when the process died as the result of a signal.
+when the process died as the result of a signal. May throw
+'UserInterrupt' when using 'delegate_ctlc'.
 -}
 
 getProcessExitCode :: ProcessHandle -> IO (Maybe ExitCode)
@@ -782,6 +787,8 @@ getProcessExitCode ph@(ProcessHandle _ delegating_ctlc _) = tryLockWaitpid $ do
                         let e  | code == 0 = ExitSuccess
                                | otherwise = ExitFailure (fromIntegral code)
                         return (ClosedHandle e, (Just e, True))
+  -- endDelegateControlC after closing the handle, since it
+  -- may throw UserInterrupt
   case m_e of
     Just e | was_open && delegating_ctlc -> endDelegateControlC e
     _                                    -> return ()