IORef package:rebase

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.

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. This function imposes a memory barrier, preventing reordering; see Data.IORef#memmodel for details.

Strict version of atomicModifyIORef. This forces both the value stored in the IORef and the value returned. The new value is installed in the IORef before the returned value is forced. So

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

will increment the IORef and then throw an exception in the calling thread. This function imposes a memory barrier, preventing reordering; 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.

Strict version of modifyIORef. This is not an atomic update, consider using atomicModifyIORef' when operating in a multithreaded environment.

Build a new IORef

Read the value of an IORef. Beware that the CPU executing a thread can reorder reads or writes to independent locations. See Data.IORef#memmodel for more details.

Write a new value into an IORef. This function does not create a memory barrier and can be reordered with other independent reads and writes within a thread, which may cause issues for multithreaded execution. In these cases, consider using atomicWriteIORef instead. See Data.IORef#memmodel for more details.