stm-chans-3.0.0.4: Additional types of channels for STM.

Copyright | Copyright (c) 2011--2015 wren gayle romano
License | BSD
Maintainer | wren@community.haskell.org
Stability | provisional
Portability | non-portable (GHC STM, DeriveDataTypeable)
Safe Haskell | Trustworthy
Language | Haskell98

Control.Concurrent.STM.TBChan

Contents

- The TBChan type
  - Creating TBChans
  - Reading from TBChans
  - Writing to TBChans
  - Predicates
  - Other functionality

Description

A version of Control.Concurrent.STM.TChan where the queue is bounded in length. This variant incorporates ideas from Thomas M. DuBuisson's `bounded-tchan` package in order to reduce contention between readers and writers.

Synopsis

- data TBChan a
- newTBChan :: Int -> STM (TBChan a)
- newTBChanIO :: Int -> IO (TBChan a)
- readTBChan :: TBChan a -> STM a
- tryReadTBChan :: TBChan a -> STM (Maybe a)
- peekTBChan :: TBChan a -> STM a
- tryPeekTBChan :: TBChan a -> STM (Maybe a)
- writeTBChan :: TBChan a -> a -> STM ()
- tryWriteTBChan :: TBChan a -> a -> STM Bool
- unGetTBChan :: TBChan a -> a -> STM ()
- isEmptyTBChan :: TBChan a -> STM Bool
- isFullTBChan :: TBChan a -> STM Bool
- estimateFreeSlotsTBChan :: TBChan a -> STM Int
- freeSlotsTBChan :: TBChan a -> STM Int

# The TBChan type

data TBChan a

`TBChan` is an abstract type representing a bounded FIFO channel.

## Creating TBChans

newTBChan :: Int -> STM (TBChan a)

Build and returns a new instance of `TBChan` with the given capacity. N.B., we do not verify the capacity is positive, but if it is non-positive then `writeTBChan` will always retry and `isFullTBChan` will always be true.

newTBChanIO :: Int -> IO (TBChan a)

`IO` version of `newTBChan`. This is useful for creating top-level `TBChan`s using `unsafePerformIO`, because using `atomically` inside `unsafePerformIO` isn't possible.

## Reading from TBChans

readTBChan :: TBChan a -> STM a

Read the next value from the `TBChan`, retrying if the channel is empty.

tryReadTBChan :: TBChan a -> STM (Maybe a)

A version of `readTBChan` which does not retry. Instead it returns `Nothing` if no value is available.

peekTBChan :: TBChan a -> STM a

Get the next value from the `TBChan` without removing it, retrying if the channel is empty.

tryPeekTBChan :: TBChan a -> STM (Maybe a)

A version of `peekTBChan` which does not retry. Instead it returns `Nothing` if no value is available.

## Writing to TBChans

writeTBChan :: TBChan a -> a -> STM ()

Write a value to a `TBChan`, retrying if the channel is full.

tryWriteTBChan :: TBChan a -> a -> STM Bool

A version of `writeTBChan` which does not retry. Returns `True` if the value was successfully written, and `False` otherwise.

unGetTBChan :: TBChan a -> a -> STM ()

Put a data item back onto a channel, where it will be the next item read. N.B., this could allow the channel to temporarily become longer than the specified limit, which is necessary to ensure that the item is indeed the next one read.

## Predicates

isEmptyTBChan :: TBChan a -> STM Bool

Returns `True` if the supplied `TBChan` is empty (i.e., has no elements). N.B., a `TBChan` can be both ``empty'` and ``full'` at the same time, if the initial limit was non-positive.

isFullTBChan :: TBChan a -> STM Bool

Returns `True` if the supplied `TBChan` is full (i.e., is over its limit). N.B., a `TBChan` can be both ``empty'` and ``full'` at the same time, if the initial limit was non-positive. N.B., a `TBChan` may still be full after reading, if `unGetTBChan` was used to go over the initial limit.

This is equivalent to: `liftM (<= 0) estimateFreeSlotsTBMChan`

## Other functionality

estimateFreeSlotsTBChan :: TBChan a -> STM Int

Estimate the number of free slots. If the result is positive, then it's a minimum bound; if it's non-positive then it's exact. It will only be negative if the initial limit was negative or if `unGetTBChan` was used to go over the initial limit.

This function always contends with writers, but only contends with readers when it has to; compare against `freeSlotsTBChan`.

freeSlotsTBChan :: TBChan a -> STM Int

Return the exact number of free slots. The result can be negative if the initial limit was negative or if `unGetTBChan` was used to go over the initial limit.

This function always contends with both readers and writers; compare against `estimateFreeSlotsTBChan`.