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 #ifndef __NHC__
  56 -- import Data.Dynamic
  57 #endif
  58
  59 #if defined(__GLASGOW_HASKELL__) && !defined(__PARALLEL_HASKELL__)
  60 -- |Make a 'Weak' pointer to an 'IORef'
  61 mkWeakIORef :: IORef a -> IO () -> IO (Weak (IORef a))
  62 mkWeakIORef r@(IORef (STRef r#)) f = IO $ \s ->
  63   case mkWeak# r# r f s of (# s1, w #) -> (# s1, Weak w #)
  64 #endif
  65
  66 -- |Mutate the contents of an 'IORef'
  67 modifyIORef :: IORef a -> (a -> a) -> IO ()
  68 modifyIORef ref f = writeIORef ref . f =<< readIORef ref
  69
  70
  71 -- |Atomically modifies the contents of an 'IORef'.
  72 --
  73 -- This function is useful for using 'IORef' in a safe way in a multithreaded
  74 -- program.  If you only have one 'IORef', then using 'atomicModifyIORef' to
  75 -- access and modify it will prevent race conditions.
  76 --
  77 -- Extending the atomicity to multiple 'IORef's is problematic, so it
  78 -- is recommended that if you need to do anything more complicated
  79 -- then using 'MVar' instead is a good idea.
  80 --
  81 atomicModifyIORef :: IORef a -> (a -> (a,b)) -> IO b
  82 #if defined(__GLASGOW_HASKELL__)
  83 atomicModifyIORef (IORef (STRef r#)) f = IO $ \s -> atomicModifyMutVar# r# f s
  84
  85 #elif defined(__HUGS__)
  86 atomicModifyIORef = plainModifyIORef    -- Hugs has no preemption
  87   where plainModifyIORef r f = do
  88                 a <- readIORef r
  89                 case f a of (a',b) -> writeIORef r a' >> return b
  90 #elif defined(__NHC__)
  91 atomicModifyIORef r f =
  92   excludeFinalisers $ do
  93     a <- readIORef r
  94     let (a',b) = f a
  95     writeIORef r a'
  96     return b
  97 #endif