[project @ 2004-10-17 00:08:08 by ross]
[packages/random.git] / Data / IORef.hs
1 -----------------------------------------------------------------------------
2 -- |
3 -- Module : Data.IORef
4 -- Copyright : (c) The University of Glasgow 2001
5 -- License : BSD-style (see the file libraries/base/LICENSE)
6 --
7 -- Maintainer : libraries@haskell.org
8 -- Stability : experimental
9 -- Portability : portable
10 --
11 -- Mutable references in the IO monad.
12 --
13 -----------------------------------------------------------------------------
14
15 module Data.IORef
16 (
17 -- * IORefs
18 IORef, -- abstract, instance of: Eq, Typeable
19 newIORef, -- :: a -> IO (IORef a)
20 readIORef, -- :: IORef a -> IO a
21 writeIORef, -- :: IORef a -> a -> IO ()
22 modifyIORef, -- :: IORef a -> (a -> a) -> IO ()
23 atomicModifyIORef, -- :: IORef a -> (a -> (a,b)) -> IO b
24
25 #if !defined(__PARALLEL_HASKELL__) && defined(__GLASGOW_HASKELL__)
26 mkWeakIORef, -- :: IORef a -> IO () -> IO (Weak (IORef a))
27 #endif
28 ) where
29
30 import Prelude -- Explicit dependency helps 'make depend' do the right thing
31
32 #ifdef __HUGS__
33 import Hugs.IORef
34 #endif
35
36 #ifdef __GLASGOW_HASKELL__
37 import GHC.Base ( mkWeak#, atomicModifyMutVar# )
38 import GHC.STRef
39 import GHC.IOBase
40 #if !defined(__PARALLEL_HASKELL__)
41 import GHC.Weak
42 #endif
43 #endif /* __GLASGOW_HASKELL__ */
44
45 #ifdef __NHC__
46 import NHC.IOExtras
47 ( IORef
48 , newIORef
49 , readIORef
50 , writeIORef
51 , excludeFinalisers
52 )
53 #endif
54
55 #if defined(__GLASGOW_HASKELL__) && !defined(__PARALLEL_HASKELL__)
56 -- |Make a 'Weak' pointer to an 'IORef'
57 mkWeakIORef :: IORef a -> IO () -> IO (Weak (IORef a))
58 mkWeakIORef r@(IORef (STRef r#)) f = IO $ \s ->
59 case mkWeak# r# r f s of (# s1, w #) -> (# s1, Weak w #)
60 #endif
61
62 -- |Mutate the contents of an 'IORef'
63 modifyIORef :: IORef a -> (a -> a) -> IO ()
64 modifyIORef ref f = writeIORef ref . f =<< readIORef ref
65
66
67 -- |Atomically modifies the contents of an 'IORef'.
68 --
69 -- This function is useful for using 'IORef' in a safe way in a multithreaded
70 -- program. If you only have one 'IORef', then using 'atomicModifyIORef' to
71 -- access and modify it will prevent race conditions.
72 --
73 -- Extending the atomicity to multiple 'IORef's is problematic, so it
74 -- is recommended that if you need to do anything more complicated
75 -- then using 'Control.Concurrent.MVar.MVar' instead is a good idea.
76 --
77 atomicModifyIORef :: IORef a -> (a -> (a,b)) -> IO b
78 #if defined(__GLASGOW_HASKELL__)
79 atomicModifyIORef (IORef (STRef r#)) f = IO $ \s -> atomicModifyMutVar# r# f s
80
81 #elif defined(__HUGS__)
82 atomicModifyIORef = plainModifyIORef -- Hugs has no preemption
83 where plainModifyIORef r f = do
84 a <- readIORef r
85 case f a of (a',b) -> writeIORef r a' >> return b
86 #elif defined(__NHC__)
87 atomicModifyIORef r f =
88 excludeFinalisers $ do
89 a <- readIORef r
90 let (a',b) = f a
91 writeIORef r a'
92 return b
93 #endif