base-4.20.2.0: Core data structures and operations

Copyright | (c) The University of Glasgow 2008
License | see libraries/base/LICENSE
Maintainer | ghc-devs@haskell.org
Stability | internal
Portability | non-portable (GHC Extensions)
Safe Haskell | None
Language | Haskell2010

GHC.IORef

Description

The IORef type

Synopsis

- newtype IORef a = IORef (STRef RealWorld a)
- newIORef :: a -> IO (IORef a)
- readIORef :: IORef a -> IO a
- writeIORef :: IORef a -> a -> IO ()
- atomicModifyIORef2Lazy :: IORef a -> (a -> (a, b)) -> IO (a, (a, b))
- atomicModifyIORef2 :: IORef a -> (a -> (a, b)) -> IO (a, (a, b))
- atomicModifyIORefLazy_ :: IORef a -> (a -> a) -> IO (a, a)
- atomicModifyIORef'_ :: IORef a -> (a -> a) -> IO (a, a)
- atomicModifyIORefP :: IORef a -> (a -> (a, b)) -> IO b
- atomicSwapIORef :: IORef a -> a -> IO a
- atomicModifyIORef' :: IORef a -> (a -> (a, b)) -> IO b

# Documentation

newtype IORef a Source #

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`.

Constructors

IORef (STRef RealWorld a) |

#### Instances

Instances details

Eq (IORef a) | Pointer equality. Since: base-4.0.0.0
Instance details Defined in GHC.Internal.IORef Methods (==) :: IORef a -> IORef a -> Bool Source # (/=) :: IORef a -> IORef a -> Bool Source #

newIORef :: a -> IO (IORef a) Source #

Build a new `IORef`

readIORef :: IORef a -> IO a Source #

Read the value of an `IORef`.

Beware that the CPU executing a thread can reorder reads or writes to independent locations. See Data.IORef for more details.

writeIORef :: IORef a -> a -> IO () Source #

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

atomicModifyIORef2Lazy :: IORef a -> (a -> (a, b)) -> IO (a, (a, b)) Source #

Atomically apply a function to the contents of an `IORef`, installing its first component in the `IORef` and returning the old contents and the result of applying the function. The result of the function application (the pair) is not forced. As a result, this can lead to memory leaks. It is generally better to use `atomicModifyIORef2`.

atomicModifyIORef2 :: IORef a -> (a -> (a, b)) -> IO (a, (a, b)) Source #

Atomically apply a function to the contents of an `IORef`, installing its first component in the `IORef` and returning the old contents and the result of applying the function. The result of the function application (the pair) is forced, but neither of its components is.

atomicModifyIORefLazy_ :: IORef a -> (a -> a) -> IO (a, a) Source #

Atomically apply a function to the contents of an `IORef` and return the old and new values. The result of the function is not forced. As this can lead to a memory leak, it is usually better to use `atomicModifyIORef'_`.

atomicModifyIORef'_ :: IORef a -> (a -> a) -> IO (a, a) Source #

Atomically apply a function to the contents of an `IORef` and return the old and new values. The result of the function is forced.

atomicModifyIORefP :: IORef a -> (a -> (a, b)) -> IO b Source #

A version of `atomicModifyIORef` that forces the (pair) result of the function.

atomicSwapIORef :: IORef a -> a -> IO a Source #

Atomically replace the contents of an `IORef`, returning the old contents.

atomicModifyIORef' :: IORef a -> (a -> (a, b)) -> IO b Source #

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