Copyright	(c) The University of Glasgow 2001
License	BSD-style (see the file libraries/base/LICENSE)
Maintainer	libraries@haskell.org
Stability	experimental
Portability	portable
Safe Haskell	Trustworthy
Language	Haskell2010

Data.IORef

Contents

IORefs
- Memory Model

Description

Mutable references in the IO monad.

Synopsis

IORefs

data IORef a Source

A mutable variable in the IO monad

Instances

Typeable1 IORef
Eq (IORef a)
Typeable (* -> *) IORef

newIORef :: a -> IO (IORef a) Source

Build a new IORef

readIORef :: IORef a -> IO a Source

Read the value of an IORef

writeIORef :: IORef a -> a -> IO () Source

Write a new value into an IORef

modifyIORef :: IORef a -> (a -> a) -> IO () Source

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.

modifyIORef' :: IORef a -> (a -> a) -> IO () Source

Strict version of modifyIORef

Since: 4.6.0.0

atomicModifyIORef :: IORef a -> (a -> (a, b)) -> IO b Source

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 IORefs is problematic, so it is recommended that if you need to do anything more complicated then using MVar instead is a good idea.

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.

atomicModifyIORef' :: IORef a -> (a -> (a, b)) -> IO b Source

Strict version of atomicModifyIORef. This forces both the value stored in the IORef as well as the value returned.

Since: 4.6.0.0

atomicWriteIORef :: IORef a -> a -> IO () Source

Variant of writeIORef with the "barrier to reordering" property that atomicModifyIORef has.

Since: 4.6.0.0

mkWeakIORef :: IORef a -> IO () -> IO (Weak (IORef a)) Source

Make a Weak pointer to an IORef, using the second argument as a finalizer to run when IORef is garbage-collected

Memory Model

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

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.