Control.Concurrent.Broadcast

concurrent-extra-0.7.0.9: Extra concurrency primitives

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 ``listen`ers` wait until a broadcaster ``broadcast`s` 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

- data Broadcast a
- new :: IO (Broadcast a)
- newBroadcasting :: a -> IO (Broadcast a)
- listen :: Broadcast a -> IO a
- tryListen :: Broadcast a -> IO (Maybe a)
- listenTimeout :: Broadcast a -> Integer -> IO (Maybe a)
- broadcast :: Broadcast a -> a -> IO ()
- signal :: Broadcast a -> a -> IO ()
- silence :: Broadcast a -> IO ()

# Documentation

data Broadcast a

A broadcast is in one of two possible states:

- "Silent": ``listen`ing` to the broadcast will block until a value is ``broadcast`ed`.
- "Broadcasting `x`": ``listen`ing` to the broadcast will return the value `x` without blocking.

Instances

Eq (Broadcast a) |

# 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 ``broadcast`s` 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 ``listen`ing` 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 ``listen`ing` 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.