Improve documentation of atomically

diff --git a/GHC/Conc.lhs b/GHC/Conc.lhs
index 0b6bc91..f24b61d 100644 (file)
--- a/GHC/Conc.lhs
+++ b/GHC/Conc.lhs
@@ -328,6 +328,15 @@ unsafeIOToSTM :: IO a -> STM a
 unsafeIOToSTM (IO m) = STM m
 
 -- |Perform a series of STM actions atomically.
+--
+-- You cannot use 'atomically' inside an 'unsafePerformIO' or 'unsafeInterleaveIO'. 
+-- Any attempt to do so will result in a runtime error.  (Reason: allowing
+-- this would effectively allow a transaction inside a transaction, depending
+-- on exactly when the thunk is evaluated.)
+--
+-- However, see 'newTVarIO', which can be called inside 'unsafePerformIO',
+-- and which allows top-level TVars to be allocated.
+
 atomically :: STM a -> IO a
 atomically (STM m) = IO (\s -> (atomically# m) s )