Data.IORef.AtomicModify

Atomic IORef and array modification operations for more general result types.

Documentation

atomicModifyIORef3General :: IORef a -> (t -> a) -> (a -> t) -> IO (a, a, t)

A version of atomicModifyIORef2 that takes an arbitrary pair of functions. This function will allocate more than atomicModifyIORef2, and will tend to take longer to succeed when there is a lot of contention for the IORef.

atomicModifyIORef2 ref f = do
  (old, _new, r) <- atomicModifyIORef2General ref fst f
  pure (old, r)

If the first function (the "extraction function") is a record field selector (e.g., snd), we do our best to make sure the thunk placed in the IORef is a selector thunk, so the garbage collector can drop the rest of the record once the record is forced. In other cases, callers should generally force the returned new value in order to avoid a potential space leak.

Conceptually:

atomicModifyIORef3General ref extract f = do
  -- Begin atomic block
  old <- readIORef ref
  let r = f old
      new = extract r
  writeIORef ref new
  -- End atomic block
  r seq pure (old, new, r)

where other threads cannot interfere with the operations in the "atomic block". In particular, no other thread can write to the IORef between the readIORef and the writeIORef operations.

atomicModifyArray3General :: MutableArray RealWorld a -> Int -> (t -> a) -> (a -> t) -> IO (a, a, t)

A version of atomicModifyIORef3General for Arrays. See the documentation there. Indexing is performed safely.

atomicModifySmallArray3General :: SmallMutableArray RealWorld a -> Int -> (t -> a) -> (a -> t) -> IO (a, a, t)

A version of atomicModifyIORef3General for SmallArrays. See the documentation there. Indexing is performed safely.