+{-# LANGUAGE CPP, NoImplicitPrelude, MagicHash, UnboxedTuples #-}
+
-----------------------------------------------------------------------------
---
+-- |
-- Module : Data.IORef
-- Copyright : (c) The University of Glasgow 2001
--- License : BSD-style (see the file libraries/core/LICENSE)
+-- License : BSD-style (see the file libraries/base/LICENSE)
--
-- Maintainer : libraries@haskell.org
-- Stability : experimental
--- Portability : non-portable
---
--- $Id: IORef.hs,v 1.1 2001/06/28 14:15:02 simonmar Exp $
+-- Portability : portable
--
-- Mutable references in the IO monad.
--
-----------------------------------------------------------------------------
module Data.IORef
- ( IORef -- abstract, instance of: Eq, Typeable
- , newIORef -- :: a -> IO (IORef a)
- , readIORef -- :: IORef a -> IO a
- , writeIORef -- :: IORef a -> a -> IO ()
- , modifyIORef -- :: IORef a -> (a -> a) -> IO ()
+ (
+ -- * IORefs
+ IORef, -- abstract, instance of: Eq, Typeable
+ newIORef, -- :: a -> IO (IORef a)
+ readIORef, -- :: IORef a -> IO a
+ writeIORef, -- :: IORef a -> a -> IO ()
+ modifyIORef, -- :: IORef a -> (a -> a) -> IO ()
+ atomicModifyIORef, -- :: IORef a -> (a -> (a,b)) -> IO b
#if !defined(__PARALLEL_HASKELL__) && defined(__GLASGOW_HASKELL__)
- , mkWeakIORef -- :: IORef a -> IO () -> IO (Weak (IORef a))
+ mkWeakIORef, -- :: IORef a -> IO () -> IO (Weak (IORef a))
#endif
- ) where
+ -- ** Memory Model
-import Prelude
+ -- $memmodel
+
+ ) where
+
+#ifdef __HUGS__
+import Hugs.IORef
+#endif
#ifdef __GLASGOW_HASKELL__
-import GHC.Prim ( mkWeak# )
+import GHC.Base
import GHC.STRef
-import GHC.IOBase
+-- import GHC.IO
+import GHC.IORef hiding (atomicModifyIORef)
+import qualified GHC.IORef
#if !defined(__PARALLEL_HASKELL__)
import GHC.Weak
#endif
#endif /* __GLASGOW_HASKELL__ */
-#ifdef __HUGS__
-import IOExts ( IORef, newIORef, writeIORef, readIORef )
-import ST ( stToIO, newSTRef, readSTRef, writeSTRef )
+#ifdef __NHC__
+import NHC.IOExtras
+ ( IORef
+ , newIORef
+ , readIORef
+ , writeIORef
+ , excludeFinalisers
+ )
#endif
-import Data.Dynamic
-
-#ifndef __PARALLEL_HASKELL__
+#if defined(__GLASGOW_HASKELL__) && !defined(__PARALLEL_HASKELL__)
+-- |Make a 'Weak' pointer to an 'IORef', using the second argument as a finalizer
+-- to run when 'IORef' is garbage-collected
mkWeakIORef :: IORef a -> IO () -> IO (Weak (IORef a))
mkWeakIORef r@(IORef (STRef r#)) f = IO $ \s ->
case mkWeak# r# r f s of (# s1, w #) -> (# s1, Weak w #)
#endif
+-- |Mutate the contents of an 'IORef'
modifyIORef :: IORef a -> (a -> a) -> IO ()
-modifyIORef ref f = writeIORef ref . f =<< readIORef ref
+modifyIORef ref f = readIORef ref >>= writeIORef ref . f
+
+
+-- |Atomically modifies the contents of an 'IORef'.
+--
+-- This function is useful for using 'IORef' in a safe way in a multithreaded
+-- program. If you only have one 'IORef', then using 'atomicModifyIORef' to
+-- access and modify it will prevent race conditions.
+--
+-- Extending the atomicity to multiple 'IORef's is problematic, so it
+-- is recommended that if you need to do anything more complicated
+-- then using 'Control.Concurrent.MVar.MVar' instead is a good idea.
+--
+atomicModifyIORef :: IORef a -> (a -> (a,b)) -> IO b
+#if defined(__GLASGOW_HASKELL__)
+atomicModifyIORef = GHC.IORef.atomicModifyIORef
+
+#elif defined(__HUGS__)
+atomicModifyIORef = plainModifyIORef -- Hugs has no preemption
+ where plainModifyIORef r f = do
+ a <- readIORef r
+ case f a of (a',b) -> writeIORef r a' >> return b
+#elif defined(__NHC__)
+atomicModifyIORef r f =
+ excludeFinalisers $ do
+ a <- readIORef r
+ let (a',b) = f a
+ writeIORef r a'
+ return b
+#endif
+
+{- $memmodel
+
+ In a concurrent program, 'IORef' operations may appear out-of-order
+ to another thread, depending on the memory model of the underlying
+ processor architecture. For example, on x86, loads can move ahead
+ of stores, so in the following example:
+
+> maybePrint :: IORef Bool -> IORef Bool -> IO ()
+> maybePrint myRef yourRef = do
+> writeIORef myRef True
+> yourVal <- readIORef yourRef
+> unless yourVal $ putStrLn "critical section"
+>
+> main :: IO ()
+> main = do
+> r1 <- newIORef False
+> r2 <- newIORef False
+> forkIO $ maybePrint r1 r2
+> forkIO $ maybePrint r2 r1
+> threadDelay 1000000
+
+ it is possible that the string @"critical section"@ is printed
+ twice, even though there is no interleaving of the operations of the
+ two threads that allows that outcome. The memory model of x86
+ allows 'readIORef' to happen before the earlier 'writeIORef'.
+
+ The implementation is required to ensure that reordering of memory
+ operations cannot cause type-correct code to go wrong. In
+ particular, when inspecting the value read from an 'IORef', the
+ memory writes that created that value must have occurred from the
+ point of view of the current therad.
+
+ 'atomicModifyIORef' acts as a barrier to reordering. Multiple
+ 'atomicModifyIORef' operations occur in strict program order. An
+ 'atomicModifyIORef' is never observed to take place ahead of any
+ earlier (in program order) 'IORef' operations, or after any later
+ 'IORef' operations.
-#include "Dynamic.h"
-INSTANCE_TYPEABLE1(IORef,ioRefTc,"IORef")
+-}