From: simonpj@microsoft <unknown>
Date: Fri, 14 Jul 2006 12:02:07 +0000 (+0000)
Subject: Improve documentation of atomically
X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=b53fd4a2af7c7b22b54875de8b0befc8fb6518a2;p=haskell-directory.git

Improve documentation of atomically
---

diff --git a/GHC/Conc.lhs b/GHC/Conc.lhs
index 0b6bc91..f24b61d 100644
--- 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 )