|Maintainer||Bas van Dijk <firstname.lastname@example.org> , Roel van Dijk <email@example.com>|
This module provides the
RLock synchronisation mechanism. It was inspired
by the Python
RLock and Java
ReentrantLock objects and should behave in a
similar way. See:
All functions are exception safe. Throwing asynchronous exceptions will not
compromise the internal state of an
This module is intended to be imported qualified. We suggest importing it like:
import Control.Concurrent.RLock ( RLock ) import qualified Control.Concurrent.RLock as RLock ( ... )
A reentrant lock is in one of two states: "locked" or "unlocked". When the lock is in the "locked" state it has two additional properties:
- Its owner: the thread that acquired the lock.
- Its acquired count: how many times its owner acquired the lock.
Creating reentrant locks
Create a reentrant lock in the "locked" state (with the current thread as owner and an acquired count of 1).
Locking and unlocking
acquire behaves as follows:
- When the state is "unlocked",
acquirechanges the state to "locked" with the current thread as owner and an acquired count of 1.
- When the state is "locked" and the current thread owns the lock
acquireonly increments the acquired count.
- When the state is "locked" and the current thread does not own the lock
acquireblocks until the owner releases the lock. If the thread that called
acquireis woken upon release of the lock it will take ownership and change the state to "locked" with an acquired count of 1.
There are two further important properties of
acquireis 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
- When multiple threads are blocked on
acquirethey 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.)
release decrements the acquired count. When a lock is released with an
acquired count of 1 its state is changed to "unlocked".
Note that it is both an error to release a lock in the "unlocked" state and to release a lock that is not owned by the current thread.
If there are any threads blocked on
acquire the thread that first called
acquire will be woken up.
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.
- When the state is "locked"
waitblocks until a call to
releasein another thread changes it to "unlocked".
- When the state is "unlocked"
wait does not alter the state of the lock.
wait is just a convenience function defined as: