Control.Concurrent.STM.Lock

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 | Trustworthy
Language | Haskell98

Control.Concurrent.STM.Lock

Contents

- Creating locks
- Locking and unlocking
- Convenience functions
- Querying locks

Description

This module provides an `STM` version of `Control.Concurrent.Lock`.

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

    import           Control.Concurrent.STM.Lock         ( Lock )
    import qualified Control.Concurrent.STM.Lock as Lock ( ... )

Synopsis

- data Lock
- new :: STM Lock
- newAcquired :: STM Lock
- acquire :: Lock -> STM ()
- tryAcquire :: Lock -> STM Bool
- release :: Lock -> STM ()
- with :: Lock -> IO a -> IO a
- tryWith :: Lock -> IO a -> IO (Maybe a)
- wait :: Lock -> STM ()
- locked :: Lock -> STM Bool

# Documentation

data Lock

A lock is in one of two states: "locked" or "unlocked".

Instances

Eq Lock |

# Creating locks

new :: STM Lock

Create a lock in the "unlocked" state.

newAcquired :: STM Lock

Create a lock in the "locked" state.

# Locking and unlocking

acquire :: Lock -> STM ()

- When the state is "locked" `acquire` will `retry` the transaction.
- When the state is "unlocked" `acquire` will change the state to "locked".

tryAcquire :: Lock -> STM Bool

A non-blocking `acquire`.

- When the state is "unlocked" `tryAcquire` changes the state to "locked" and returns `True`.
- When the state is "locked" `tryAcquire` leaves the state unchanged and returns `False`.

release :: Lock -> STM ()

`release` changes the state to "unlocked" and returns immediately.

Note that it is an error to release a lock in the "unlocked" state!

# Convenience functions

with :: Lock -> IO a -> IO a

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

tryWith :: Lock -> IO a -> IO (Maybe a)

A non-blocking `with`. `tryWith` is a convenience function which 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.

wait :: Lock -> STM ()

- When the state is "locked", `wait` will `retry` the transaction
- When the state is "unlocked" `wait` returns immediately.

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

Note that `wait` is just a convenience function which can be defined as:

    wait l = acquire l >> release l

# Querying locks

locked :: Lock -> STM Bool

Determines if the lock is in the "locked" state.

Note that this is only a snapshot of the state. By the time a program reacts on its result it may already be out of date.