Data.IORef.Strict

A mutable variable in the IO monad, which evaluates its content to Weak Head Normal Form.

Build a new IORef.

Evaluates the initial value to WHNF.

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.

Evaluates the new value to WHNF.

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.

Evaluates the new value to WHNF.

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.

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.

Evaluates both the new value and the returned value to WHNF.

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.

Evaluates the new value to WHNF.

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