[commit: base] master: document the behaviour of throwTo to the current thread (#4888) (d8c8a1a)

[Simon Marlow]

Repository : ssh://darcs.haskell.org//srv/darcs/packages/base

On branch  : master

http://hackage.haskell.org/trac/ghc/changeset/d8c8a1a857709334949d680d6afa274b7c6c7809

>---------------------------------------------------------------

commit d8c8a1a857709334949d680d6afa274b7c6c7809
Author: Simon Marlow <marlowsd at gmail.com>
Date:   Tue May 24 11:02:52 2011 +0100

    document the behaviour of throwTo to the current thread (#4888)

>---------------------------------------------------------------

 GHC/Conc/Sync.lhs |   14 +++++++++++---
 1 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/GHC/Conc/Sync.lhs b/GHC/Conc/Sync.lhs
index 0214a56..f16ee3f 100644
--- a/GHC/Conc/Sync.lhs
+++ b/GHC/Conc/Sync.lhs
@@ -373,9 +373,17 @@ thread reaches a /safe point/, where a safe point is where memory
 allocation occurs.  Some loops do not perform any memory allocation
 inside the loop and therefore cannot be interrupted by a 'throwTo'.
 
-Blocked 'throwTo' is fair: if multiple threads are trying to throw an
-exception to the same target thread, they will succeed in FIFO order.
-
+If the target of 'throwTo' is the calling thread, then the behaviour
+is the same as 'Control.Exception.throwIO', except that the exception
+is thrown as an asynchronous exception.  This means that if there is
+an enclosing pure computation, which would be the case if the current
+IO operation is inside 'unsafePerformIO' or 'unsafeInterleaveIO', that
+computation is not permanently replaced by the exception, but is
+suspended as if it had received an asynchronous exception.
+
+Note that if 'throwTo' is called with the current thread as the
+target, the exception will be thrown even if the thread is currently
+inside 'mask' or 'uninterruptibleMask'.
   -}
 throwTo :: Exception e => ThreadId -> e -> IO ()
 throwTo (ThreadId tid) ex = IO $ \ s ->