From e0f3d371d7746a0f27af988fb51f4552e5e05cd2 Mon Sep 17 00:00:00 2001 From: Simon Marlow Date: Wed, 30 Jul 2008 11:45:54 +0000 Subject: [PATCH] add some big warnings to the docs for unsafeIOToSTM (#2401) --- GHC/Conc.lhs | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/GHC/Conc.lhs b/GHC/Conc.lhs index 9ddb9c4..8c34527 100644 --- a/GHC/Conc.lhs +++ b/GHC/Conc.lhs @@ -440,7 +440,26 @@ thenSTM (STM m) k = STM ( \s -> returnSTM :: a -> STM a returnSTM x = STM (\s -> (# s, x #)) --- | Unsafely performs IO in the STM monad. +-- | Unsafely performs IO in the STM monad. Beware: this is a highly +-- dangerous thing to do. +-- +-- * The STM implementation will often run transactions multiple +-- times, so you need to be prepared for this if your IO has any +-- side effects. +-- +-- * The STM implementation will abort transactions that are known to +-- be invalid and need to be restarted. This may happen in the middle +-- of `unsafeIOToSTM`, so make sure you don't acquire any resources +-- that need releasing (exception handlers are ignored when aborting +-- the transaction). That includes doing any IO using Handles, for +-- example. Getting this wrong will probably lead to random deadlocks. +-- +-- * The transaction may have seen an inconsistent view of memory when +-- the IO runs. Invariants that you expect to be true throughout +-- your program may not be true inside a transaction, due to the +-- way transactions are implemented. Normally this wouldn't be visible +-- to the programmer, but using `unsafeIOToSTM` can expose it. +-- unsafeIOToSTM :: IO a -> STM a unsafeIOToSTM (IO m) = STM m -- 1.7.10.4