From b53fd4a2af7c7b22b54875de8b0befc8fb6518a2 Mon Sep 17 00:00:00 2001
From: "simonpj@microsoft" <unknown>
Date: Fri, 14 Jul 2006 12:02:07 +0000
Subject: [PATCH] Improve documentation of atomically

---
 GHC/Conc.lhs |    9 +++++++++
 1 file changed, 9 insertions(+)

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 )
 
-- 
1.7.10.4