Documentation

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

Since: base-4.6.0.0

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 for details.

Since: base-4.6.0.0

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.

Since: base-4.6.0.0