Copyright	(c) 2010-2011 Bas van Dijk & Roel van Dijk
License	BSD3 (see the file LICENSE)
Maintainer	Bas van Dijk <v.dijk.bas@gmail.com> , Roel van Dijk <vandijk.roel@gmail.com>
Safe Haskell	Safe
Language	Haskell98

Control.Concurrent.Broadcast

Contents

Creating broadcasts
Listening to broadcasts
Broadcasting

Description

A Broadcast is a mechanism for communication between threads. Multiple listeners wait until a broadcaster broadcasts a value. The listeners block until the value is received. When the broadcaster broadcasts a value all listeners are woken.

All functions are exception safe. Throwing asynchronous exceptions will not compromise the internal state of a broadcast.

This module is designed to be imported qualified. We suggest importing it like:

import           Control.Concurrent.Broadcast              ( Broadcast )
import qualified Control.Concurrent.Broadcast as Broadcast ( ... )

Synopsis

Documentation

data Broadcast a

A broadcast is in one of two possible states:

"Silent": listening to the broadcast will block until a value is broadcasted.
"Broadcasting x": listening to the broadcast will return the value x without blocking.

Instances

Eq (Broadcast a)
Typeable (* -> *) Broadcast

Creating broadcasts

new :: IO (Broadcast a)

new creates a broadcast in the "silent" state.

newBroadcasting :: a -> IO (Broadcast a)

newBroadcasting x creates a broadcast in the "broadcasting x" state.

Listening to broadcasts

listen :: Broadcast a -> IO a

Listen to a broadcast.

If the broadcast is "broadcasting x", listen will return x immediately.
If the broadcast is "silent", listen will block until another thread broadcasts a value to the broadcast.

tryListen :: Broadcast a -> IO (Maybe a)

Try to listen to a broadcast; non blocking.

If the broadcast is "broadcasting x", tryListen will return Just x immediately.
If the broadcast is "silent", tryListen returns Nothing immediately.

listenTimeout :: Broadcast a -> Integer -> IO (Maybe a)

Listen to a broadcast if it is available within a given amount of time.

Like listen, but with a timeout. A return value of Nothing indicates a timeout occurred.

The timeout is specified in microseconds.

If the broadcast is "silent" and a timeout of 0 μs is specified the function returns Nothing without blocking.

Negative timeouts are treated the same as a timeout of 0 μs.

Broadcasting

broadcast :: Broadcast a -> a -> IO ()

Broadcast a value.

broadcast b x changes the state of the broadcast b to "broadcasting x".

If the broadcast was "silent" all threads that are listening to the broadcast will be woken.

signal :: Broadcast a -> a -> IO ()

Broadcast a value before becoming "silent".

The state of the broadcast is changed to "silent" after all threads that are listening to the broadcast are woken and resume with the signalled value.

The semantics of signal are equivalent to the following definition:

  signal b x = block $ broadcast b x >> silence b

silence :: Broadcast a -> IO ()

Set a broadcast to the "silent" state.