IORef.hs 5.24 KB
Newer Older
1
{-# LANGUAGE Trustworthy #-}
thomie's avatar
thomie committed
2
{-# LANGUAGE NoImplicitPrelude, MagicHash, UnboxedTuples #-}
3

4
-----------------------------------------------------------------------------
5
-- |
6 7
-- Module      :  Data.IORef
-- Copyright   :  (c) The University of Glasgow 2001
8
-- License     :  BSD-style (see the file libraries/base/LICENSE)
9 10 11
-- 
-- Maintainer  :  libraries@haskell.org
-- Stability   :  experimental
12
-- Portability :  portable
13 14 15 16 17 18
--
-- Mutable references in the IO monad.
--
-----------------------------------------------------------------------------

module Data.IORef
19
  ( 
Don Stewart's avatar
Don Stewart committed
20 21
        -- * IORefs
        IORef,                -- abstract, instance of: Eq, Typeable
22 23 24 25 26 27 28
        newIORef,
        readIORef,
        writeIORef,
        modifyIORef,
        modifyIORef',
        atomicModifyIORef,
        atomicModifyIORef',
29
        atomicWriteIORef,
30
        mkWeakIORef,
31 32 33 34
        -- ** Memory Model

        -- $memmodel

Don Stewart's avatar
Don Stewart committed
35
        ) where
36

37
import GHC.Base
38
import GHC.STRef
39 40
import GHC.IORef hiding (atomicModifyIORef)
import qualified GHC.IORef
41 42
import GHC.Weak

43 44
-- |Make a 'Weak' pointer to an 'IORef', using the second argument as a finalizer
-- to run when 'IORef' is garbage-collected
45
mkWeakIORef :: IORef a -> IO () -> IO (Weak (IORef a))
46 47 48 49 50
mkWeakIORef r@(IORef (STRef r#)) (IO f) = IO $ \s ->
    case mkWeak# r# r finalizer s of (# s1, w #) -> (# s1, Weak w #)
  where
    finalizer :: State# RealWorld -> State# RealWorld
    finalizer s' = case f s' of (# s'', () #) -> s''
51

52 53 54 55 56 57 58 59 60 61 62 63 64
-- |Mutate the contents of an 'IORef'.
--
-- Be warned that 'modifyIORef' does not apply the function strictly.  This
-- means if the program calls 'modifyIORef' many times, but seldomly uses the
-- value, thunks will pile up in memory resulting in a space leak.  This is a
-- common mistake made when using an IORef as a counter.  For example, the
-- following will likely produce a stack overflow:
--
-- >ref <- newIORef 0
-- >replicateM_ 1000000 $ modifyIORef ref (+1)
-- >readIORef ref >>= print
--
-- To avoid this problem, use 'modifyIORef'' instead.
65
modifyIORef :: IORef a -> (a -> a) -> IO ()
66
modifyIORef ref f = readIORef ref >>= writeIORef ref . f
67

68
-- |Strict version of 'modifyIORef'
69
--
70
-- @since 4.6.0.0
71 72 73 74 75
modifyIORef' :: IORef a -> (a -> a) -> IO ()
modifyIORef' ref f = do
    x <- readIORef ref
    let x' = f x
    x' `seq` writeIORef ref x'
76

77 78 79 80 81 82 83 84
-- |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
ross's avatar
ross committed
85
-- then using 'Control.Concurrent.MVar.MVar' instead is a good idea.
86
--
87 88 89 90 91 92 93 94 95
-- 'atomicModifyIORef' does not apply the function strictly.  This is important
-- to know even if all you are doing is replacing the value.  For example, this
-- will leak memory:
--
-- >ref <- newIORef '1'
-- >forever $ atomicModifyIORef ref (\_ -> ('2', ()))
--
-- Use 'atomicModifyIORef'' or 'atomicWriteIORef' to avoid this problem.
--
96
atomicModifyIORef :: IORef a -> (a -> (a,b)) -> IO b
97
atomicModifyIORef = GHC.IORef.atomicModifyIORef
98

99 100
-- | Strict version of 'atomicModifyIORef'.  This forces both the value stored
-- in the 'IORef' as well as the value returned.
101
--
102
-- @since 4.6.0.0
103 104
atomicModifyIORef' :: IORef a -> (a -> (a,b)) -> IO b
atomicModifyIORef' ref f = do
105 106 107
    b <- atomicModifyIORef ref $ \a ->
            case f a of
                v@(a',_) -> a' `seq` v
108 109 110 111
    b `seq` return b

-- | Variant of 'writeIORef' with the \"barrier to reordering\" property that
-- 'atomicModifyIORef' has.
112
--
113
-- @since 4.6.0.0
114 115 116 117 118
atomicWriteIORef :: IORef a -> a -> IO ()
atomicWriteIORef ref a = do
    x <- atomicModifyIORef ref (\_ -> (a, ()))
    x `seq` return ()

119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148
{- $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
Edward Z. Yang's avatar
Edward Z. Yang committed
149
  point of view of the current thread.
150 151 152 153 154 155 156 157

  '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.

-}
dterei's avatar
dterei committed
158