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

CopyrightCopyright (c) 2011--2013 wren gayle romano
LicenseBSD
Maintainerwren@community.haskell.org
Stabilityprovisional
Portabilitynon-portable (GHC STM, DeriveDataTypeable)
Safe HaskellTrustworthy
LanguageHaskell98

Control.Concurrent.STM.TBChan

Contents

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

The TBChan type

data TBChan a Source

TBChan is an abstract type representing a bounded FIFO channel.

Instances

Typeable (* -> *) TBChan 

Creating TBChans

newTBChan :: Int -> STM (TBChan a) Source

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) Source

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

Reading from TBChans

readTBChan :: TBChan a -> STM a Source

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

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

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

peekTBChan :: TBChan a -> STM a Source

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

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

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 () Source

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

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

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

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

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 Source

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 Source

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 Source

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 Source

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.