Control.Concurrent.ReadWriteVar

concurrent-extra-0.7.0.9: Extra concurrency primitives

Copyright | 2010—2011 Bas van Dijk & Roel van Dijk
License | BSD3 (see the file LICENSE)
Maintainer | Bas van Dijk <v.dijk.bas@gmail.com> , Roel van Dijk <vandijk.roel@gmail.com>
Safe Haskell | Safe
Language | Haskell98

Control.Concurrent.ReadWriteVar

Description

Concurrent read, sequential write variables. Comparable to an `IORef` with more advanced synchronization mechanisms. The value stored inside the `RWVar` can be read and used by multiple threads at the same time. Concurrent computations inside a `with` "block" observe the same value.

Observing and changing the contents of an `RWVar` are mutually exclusive. The `with` function will block if `modify` is active and vice-versa. Furthermore `with` is fully sequential and will also block on concurrent calls of `modify`.

The following are guaranteed deadlocks:

-     modify_ v $ const $ with v $ const undefined

-     with v $ const $ modify_ v $ const undefined

-     modify_ v $ const $ modify_ v $ const undefined

All functions are exception safe. Throwing asynchronous exceptions will not compromise the internal state of an `RWVar`. This also means that threads blocking on `with` or `modify` and friends can still be unblocked by throwing an asynchronous exception.

This module is designed to be imported qualified. We suggest importing it like:

    import           Control.Concurrent.ReadWriteVar        ( RWVar )
    import qualified Control.Concurrent.ReadWriteVar as RWV ( ... )

Synopsis

- data RWVar a
- new :: a -> IO (RWVar a)
- with :: RWVar a -> (a -> IO b) -> IO b
- tryWith :: RWVar a -> (a -> IO b) -> IO (Maybe b)
- modify_ :: RWVar a -> (a -> IO a) -> IO ()
- modify :: RWVar a -> (a -> IO (a, b)) -> IO b
- tryModify_ :: RWVar a -> (a -> IO a) -> IO Bool
- tryModify :: RWVar a -> (a -> IO (a, b)) -> IO (Maybe b)

# Documentation

data RWVar a

Concurrently readable and sequentially writable variable.

Instances

Eq (RWVar a) |

new :: a -> IO (RWVar a)

Create a new `RWVar`.

with :: RWVar a -> (a -> IO b) -> IO b

Execute an action that operates on the contents of the `RWVar`.

The action is guaranteed to have a consistent view of the stored value. Any function that attempts to `modify` the contents will block until the action is completed.

If another thread is modifying the contents of the `RWVar` this function will block until the other thread finishes its action.

tryWith :: RWVar a -> (a -> IO b) -> IO (Maybe b)

Like `with` but doesn't block. Returns `Just` the result if read access could be acquired without blocking, `Nothing` otherwise.

modify_ :: RWVar a -> (a -> IO a) -> IO ()

Modify the contents of an `RWVar`.

This function needs exclusive write access to the `RWVar`. Only one thread can modify an `RWVar` at the same time. All others will block.

modify :: RWVar a -> (a -> IO (a, b)) -> IO b

Modify the contents of an `RWVar` and return an additional value.

Like `modify_`, but allows a value to be returned (β) in addition to the modified value of the `RWVar`.

tryModify_ :: RWVar a -> (a -> IO a) -> IO Bool

Attempt to modify the contents of an `RWVar`.

Like `modify_`, but doesn't block. Returns `True` if the contents could be replaced, `False` otherwise.

tryModify :: RWVar a -> (a -> IO (a, b)) -> IO (Maybe b)

Attempt to modify the contents of an `RWVar` and return an additional value.

Like `modify`, but doesn't block. Returns `Just` the additional value if the contents could be replaced, `Nothing` otherwise.