Control.Concurrent.ReadWriteLock

concurrent-extra-0.7.0.9: Extra concurrency primitives

Copyright | (c) 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.ReadWriteLock

Contents

- Creating Read-Write Locks
- Read access
  - Blocking
  - Non-blocking
- Write access
  - Blocking
  - Non-blocking

Description

Multiple-reader, single-writer locks. Used to protect shared resources which may be concurrently read, but only sequentially written.

All functions are exception safe. Throwing asynchronous exceptions will not compromise the internal state of an `RWLock`. This means it is perfectly safe to kill a thread that is blocking on, for example, `acquireRead`.

See also Java's version: http://java.sun.com/javase/7/docs/api/java/util/concurrent/locks/ReadWriteLock.html

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

    import           Control.Concurrent.ReadWriteLock        ( RWLock )
    import qualified Control.Concurrent.ReadWriteLock as RWL ( ... )

Synopsis

- data RWLock
- new :: IO RWLock
- newAcquiredRead :: IO RWLock
- newAcquiredWrite :: IO RWLock
- acquireRead :: RWLock -> IO ()
- releaseRead :: RWLock -> IO ()
- withRead :: RWLock -> IO a -> IO a
- waitRead :: RWLock -> IO ()
- tryAcquireRead :: RWLock -> IO Bool
- tryWithRead :: RWLock -> IO a -> IO (Maybe a)
- acquireWrite :: RWLock -> IO ()
- releaseWrite :: RWLock -> IO ()
- withWrite :: RWLock -> IO a -> IO a
- waitWrite :: RWLock -> IO ()
- tryAcquireWrite :: RWLock -> IO Bool
- tryWithWrite :: RWLock -> IO a -> IO (Maybe a)

# Documentation

data RWLock

Multiple-reader, single-writer lock. Is in one of three states:

- "Free": Read or write access can be acquired without blocking.
- "Read": One or more threads have acquired read access. Blocks write access.
- "Write": A single thread has acquired write access. Blocks other threads from acquiring both read and write access.

Instances

Eq RWLock |

# Creating Read-Write Locks

new :: IO RWLock

Create a new `RWLock` in the "free" state; either read or write access can be acquired without blocking.

newAcquiredRead :: IO RWLock

Create a new `RWLock` in the "read" state; only read can be acquired without blocking.

newAcquiredWrite :: IO RWLock

Create a new `RWLock` in the "write" state; either acquiring read or write will block.

# Read access

## Blocking

acquireRead :: RWLock -> IO ()

Acquire the read lock.

Blocks if another thread has acquired write access. If `acquireRead` terminates without throwing an exception the state of the `RWLock` will be "read".

Implementation note: Throws an exception when more than (maxBound :: Int) simultaneous threads acquire the read lock. But that is unlikely.

releaseRead :: RWLock -> IO ()

Release the read lock.

If the calling thread was the last one to relinquish read access the state will revert to "free".

It is an error to release read access to an `RWLock` which is not in the "read" state.

withRead :: RWLock -> IO a -> IO a

A convenience function wich first acquires read access and then performs the computation. When the computation terminates, whether normally or by raising an exception, the read lock is released.

waitRead :: RWLock -> IO ()

- When the state is "write", `waitRead` blocks until a call to `releaseWrite` in another thread changes the state to "free".
- When the state is "free" or "read" `waitRead` returns immediately.

`waitRead` does not alter the state of the lock.

Note that `waitRead` is just a convenience function defined as:

    waitRead l = mask_ $ acquireRead l >> releaseRead l

## Non-blocking

tryAcquireRead :: RWLock -> IO Bool

Try to acquire the read lock; non blocking.

Like `acquireRead`, but doesn't block. Returns `True` if the resulting state is "read", `False` otherwise.

tryWithRead :: RWLock -> IO a -> IO (Maybe a)

A non-blocking `withRead`. First tries to acquire the lock. If that fails, `Nothing` is returned. If it succeeds, the computation is performed. When the computation terminates, whether normally or by raising an exception, the lock is released and `Just` the result of the computation is returned.

# Write access

## Blocking

acquireWrite :: RWLock -> IO ()

Acquire the write lock.

Blocks if another thread has acquired either read or write access. If `acquireWrite` terminates without throwing an exception the state of the `RWLock` will be "write".

releaseWrite :: RWLock -> IO ()

Release the write lock.

If `releaseWrite` terminates without throwing an exception the state will be "free".

It is an error to release write access to an `RWLock` which is not in the "write" state.

withWrite :: RWLock -> IO a -> IO a

A convenience function wich first acquires write access and then performs the computation. When the computation terminates, whether normally or by raising an exception, the write lock is released.

waitWrite :: RWLock -> IO ()

- When the state is "write" or "read" `waitWrite` blocks until a call to `releaseWrite` or `releaseRead` in another thread changes the state to "free".
- When the state is "free" `waitWrite` returns immediately.

`waitWrite` does not alter the state of the lock.

Note that `waitWrite` is just a convenience function defined as:

    waitWrite l = mask_ $ acquireWrite l >> releaseWrite l

## Non-blocking

tryAcquireWrite :: RWLock -> IO Bool

Try to acquire the write lock; non blocking.

Like `acquireWrite`, but doesn't block. Returns `True` if the resulting state is "write", `False` otherwise.

tryWithWrite :: RWLock -> IO a -> IO (Maybe a)

A non-blocking `withWrite`. First tries to acquire the lock. If that fails, `Nothing` is returned. If it succeeds, the computation is performed. When the computation terminates, whether normally or by raising an exception, the lock is released and `Just` the result of the computation is returned.