IORef -is:module

A mutable variable in the IO monad.

>>> import GHC.Internal.Data.IORef

>>> r <- newIORef 0

>>> readIORef r
0

>>> writeIORef r 1

>>> readIORef r
1

>>> atomicWriteIORef r 2

>>> readIORef r
2

>>> modifyIORef' r (+ 1)

>>> readIORef r
3

>>> atomicModifyIORef' r (\a -> (a + 1, ()))

>>> readIORef r
4

See also STRef and MVar.

A mutable variable in the IO monad.

>>> import GHC.Internal.Data.IORef

>>> r <- newIORef 0

>>> readIORef r
0

>>> writeIORef r 1

>>> readIORef r
1

>>> atomicWriteIORef r 2

>>> readIORef r
2

>>> modifyIORef' r (+ 1)

>>> readIORef r
3

>>> atomicModifyIORef' r (\a -> (a + 1, ()))

>>> readIORef r
4

See also STRef and MVar.

A mutable variable in the IO monad.

>>> import Data.IORef

>>> r <- newIORef 0

>>> readIORef r
0

>>> writeIORef r 1

>>> readIORef r
1

>>> atomicWriteIORef r 2

>>> readIORef r
2

>>> modifyIORef' r (+ 1)

>>> readIORef r
3

>>> atomicModifyIORef' r (\a -> (a + 1, ()))

>>> readIORef r
4

See also STRef and MVar.

A mutable variable in the IO monad

An IORef holds a single Unbox-able value.

A mutable variable in the IO monad.

>>> import Data.IORef

>>> r <- newIORef 0

>>> readIORef r
0

>>> writeIORef r 1

>>> readIORef r
1

>>> atomicWriteIORef r 2

>>> readIORef r
2

>>> modifyIORef' r (+ 1)

>>> readIORef r
3

>>> atomicModifyIORef' r (\a -> (a + 1, ()))

>>> readIORef r
4

See also STRef and MVar.

A strict (WHNF) variant of IORef.

Every IORef has a unique identifier.

Every IORef has a unique identifier.

A mutable variable in the IO monad which can hold an instance of Prim.

Not on Stackage, so not searched. Atomic compare and swap for IORefs and STRefs.

Create an IORef, with no special cleanup action.

Get the IORef affected.

Not on Stackage, so not searched. iorefs with a unique stable index

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. Conceptually,

atomicModifyIORef ref f = do
-- Begin atomic block
old <- readIORef ref
let r = f old
new = fst r
writeIORef ref new
-- End atomic block
case r of
(_new, res) -> pure res

The actions in the section labeled "atomic block" are not subject to interference from other threads. In particular, it is impossible for the value in the IORef to change between the readIORef and writeIORef invocations. The user-supplied function is applied to the value stored in the IORef, yielding a new value to store in the IORef and a value to return. After the new value is (lazily) stored in the IORef, atomicModifyIORef forces the result pair, but does not force either component of the result. To force both components, use atomicModifyIORef'. Note that

atomicModifyIORef ref (_ -> undefined)

will raise an exception in the calling thread, but will also install the bottoming value in the IORef, where it may be read by other threads. This function imposes a memory barrier, preventing reordering around the "atomic block"; see Data.IORef#memmodel for details.

A strict version of atomicModifyIORef. This forces both the value stored in the IORef and the value returned. Conceptually,

atomicModifyIORef' ref f = do
-- Begin atomic block
old <- readIORef ref
let r = f old
new = fst r
writeIORef ref new
-- End atomic block
case r of
(!_new, !res) -> pure res

The actions in the "atomic block" are not subject to interference by other threads. In particular, the value in the IORef cannot change between the readIORef and writeIORef invocations. The new value is installed in the IORef before either value is forced. So

atomicModifyIORef' ref (x -> (x+1, undefined))

will increment the IORef and then throw an exception in the calling thread.

atomicModifyIORef' ref (x -> (undefined, x))

and

atomicModifyIORef' ref (_ -> undefined)

will each raise an exception in the calling thread, but will also install the bottoming value in the IORef, where it may be read by other threads. This function imposes a memory barrier, preventing reordering around the "atomic block"; see Data.IORef#memmodel for details.

Variant of writeIORef. The prefix "atomic" relates to a fact that it imposes a reordering barrier, similar to atomicModifyIORef. Such a write will not be reordered with other reads or writes even on CPUs with weak memory model.

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

Mutate the contents of an IORef, combining readIORef and writeIORef. This is not an atomic update, consider using atomicModifyIORef when operating in a multithreaded environment. Be warned that modifyIORef does not apply the function strictly. This means if the program calls modifyIORef many times, but seldom 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.