SafeSemaphore-0.10.1: Much safer replacement for QSemN, QSem, and SampleVar

Copyright | (c) Chris Kuklewicz, 2012
License | BSD-style
Maintainer | haskell@list.mightyreason.com
Stability | experimental
Portability | non-portable (concurrency)
Safe Haskell | Safe
Language | Haskell98

Control.Concurrent.STM.SSem

Description

Very simple quantity semaphore.

Synopsis

- data SSem
- new :: Int -> STM SSem
- wait :: SSem -> STM ()
- signal :: SSem -> STM ()
- tryWait :: SSem -> STM (Maybe Int)
- waitN :: SSem -> Int -> STM ()
- signalN :: SSem -> Int -> STM ()
- tryWaitN :: SSem -> Int -> STM (Maybe Int)
- getValue :: SSem -> STM Int

# Documentation

data SSem

Instances

Eq SSem |

new :: Int -> STM SSem

Create a new semaphore with the given argument as the initially available quantity. This allows new semaphores to start with a negative, zero, or positive quantity.

wait :: SSem -> STM ()

Try to take a unit of value from the semaphore. This succeeds when the current quantity is positive, and then reduces the quantity by one. Otherwise this will `retry`. This will never result in a negative quantity. If several threads are retying then which one succeeds next is undefined -- an unlucky thread might starve.

signal :: SSem -> STM ()

Signal that single unit of the semaphore is available. This increases the available quantity by one.

tryWait :: SSem -> STM (Maybe Int)

Non-retrying version of `wait`. `tryWait s` is defined as `tryN s 1`

waitN :: SSem -> Int -> STM ()

Try to take the given value from the semaphore. This succeeds when the quantity is greater or equal to the given value, and then subtracts the given value from the quantity. Otherwise this will `retry`. This will never result in a negative quantity. If several threads are retrying then which one succeeds next is undefined -- an unlucky thread might starve.

signalN :: SSem -> Int -> STM ()

Signal that many units of the semaphore are available. This changes the available quantity by adding the passed size.

tryWaitN :: SSem -> Int -> STM (Maybe Int)

Non-retrying version of waitN. It either takes the quantity from the semaphore like waitN and returns `Just value taken` or finds insufficient quantity to take and returns Nothing

getValue :: SSem -> STM Int

Return the current quantity in the semaphore. This is potentially useful in a larger STM transaciton and less useful as `atomically getValueSem :: IO Int` due to race conditions.