concurrency-1.11.0.3: Typeclasses, functions, and data types for concurrency and STM.
Copyright© 2010-2011 Bas van Dijk & Roel van Dijk
© 2018 DFINITY Stiftung
MaintainerDFINITY USA Research <team@dfinity.org>
Safe HaskellSafe-Inferred
LanguageHaskell2010

Control.Concurrent.Classy.Lock

Description

This module provides the Lock synchronisation mechanism. It was inspired by the Python and Java Lock objects and should behave in a similar way. See:

http://docs.python.org/3.1/library/threading.html#lock-objects

and:

http://java.sun.com/javase/7/docs/api/java/util/concurrent/locks/Lock.html

All functions are exception safe. Throwing asynchronous exceptions will not compromise the internal state of a Lock.

Synopsis

Lock

data Lock m Source #

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

Since: 1.6.2.0

Instances

Instances details
Eq (MVar m ()) => Eq (Lock m) Source # 
Instance details

Defined in Control.Concurrent.Classy.Lock

Methods

(==) :: Lock m -> Lock m -> Bool #

(/=) :: Lock m -> Lock m -> Bool #

Creating locks

newLock :: MonadConc m => m (Lock m) Source #

Create a lock in the "unlocked" state.

Since: 1.6.2.0

newAcquired :: MonadConc m => m (Lock m) Source #

Create a lock in the "locked" state.

Since: 1.6.2.0

Locking and unlocking

acquire :: MonadConc m => Lock m -> m () Source #

Acquires the Lock. Blocks if another thread has acquired the Lock.

acquire behaves as follows:

  • When the state is "unlocked" acquire changes the state to "locked".
  • When the state is "locked" acquire blocks until a call to release in another thread wakes the calling thread. Upon awakening it will change the state to "locked".

There are two further important properties of acquire:

  • acquire is single-wakeup. That is, if there are multiple threads blocked on acquire and the lock is released, only one thread will be woken up. The runtime guarantees that the woken thread completes its acquire operation.
  • When multiple threads are blocked on acquire, they are woken up in FIFO order. This is useful for providing fairness properties of abstractions built using locks. Note that this differs from the Python implementation where the wake-up order is undefined.

Since: 1.6.2.0

tryAcquire :: MonadConc m => Lock m -> m Bool Source #

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.

Since: 1.6.2.0

release :: MonadConc m => Lock m -> m () Source #

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

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

If there are any threads blocked on acquire the thread that first called acquire will be woken up.

Since: 1.6.2.0

Convenience functions

with :: MonadConc m => Lock m -> m a -> m a Source #

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.

Note that: with = bracket_ <$> acquire <*> release.

Since: 1.6.2.0

tryWith :: MonadConc m => Lock m -> m a -> m (Maybe a) Source #

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.

Since: 1.6.2.0

wait :: MonadConc m => Lock m -> m () Source #

  • When the state is "locked", wait blocks until a call to release in another thread changes it to "unlocked".
  • wait is multiple-wakeup, so when multiple waiters are blocked on a Lock, all of them are woken up at the same time.
  • When the state is "unlocked" wait returns immediately.

wait does not alter the state of the lock.

Since: 1.6.2.0

Querying locks

locked :: MonadConc m => Lock m -> m Bool Source #

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.

Since: 1.6.2.0