Control.Concurrent.Classy.STM.TSem

TSem: transactional semaphores.

Deviations: There is no Eq instance for TSem type.

Documentation

data TSem stm

TSem is a transactional semaphore. It holds a certain number of units, and units may be acquired or released by waitTSem and signalTSem respectively. When the TSem is empty, waitTSem blocks.

Note that TSem has no concept of fairness, and there is no guarantee that threads blocked in waitTSem will be unblocked in the same order; in fact they will all be unblocked at the same time and will fight over the TSem. Hence TSem is not suitable if you expect there to be a high number of threads contending for the resource. However, like other STM abstractions, TSem is composable.

Since: concurrency-1.6.1.0

newTSem :: MonadSTM stm => Integer -> stm (TSem stm)

Construct new TSem with an initial counter value.

A positive initial counter value denotes availability of units waitTSem can acquire.

The initial counter value can be negative which denotes a resource "debt" that requires a respective amount of signalTSem operations to counter-balance.

Since: concurrency-1.6.1.0

waitTSem :: MonadSTM stm => TSem stm -> stm ()

Wait on TSem (aka P operation).

This operation acquires a unit from the semaphore (i.e. decreases the internal counter) and blocks (via retry) if no units are available (i.e. if the counter is not positive).

Since: concurrency-2.4.2

signalTSem :: MonadSTM stm => TSem stm -> stm ()

Signal a TSem (aka V operation).

This operation adds/releases a unit back to the semaphore (i.e. increments the internal counter).

Since: concurrency-1.6.1.0

signalTSemN :: MonadSTM stm => Natural -> TSem stm -> stm ()

Multi-signal a TSem

This operation adds/releases multiple units back to the semaphore (i.e. increments the internal counter).

signalTSem == signalTSemN 1

Since: concurrency-1.6.1.0