Control.Concurrent.Event

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.Event

Contents

- Creating events
- Waiting for events
- Setting events

Description

An Event is a simple mechanism for communication between threads: one thread signals an event and other threads wait for it.

An event has a state which is either "set" or "cleared". This state can be changed with the corresponding functions `set` and `clear`. The `wait` function blocks until the state is "set". An important property of setting an event is that all threads waiting for it are woken.

It was inspired by the Python `Event` object. See:

http://docs.python.org/3.1/library/threading.html#event-objects

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

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

Synopsis

- data Event
- new :: IO Event
- newSet :: IO Event
- wait :: Event -> IO ()
- waitTimeout :: Event -> Integer -> IO Bool
- isSet :: Event -> IO Bool
- set :: Event -> IO ()
- signal :: Event -> IO ()
- clear :: Event -> IO ()

# Documentation

data Event

An event is in one of two possible states: "set" or "cleared".

Instances

Eq Event |

# Creating events

new :: IO Event

Create an event in the "cleared" state.

newSet :: IO Event

Create an event in the "set" state.

# Waiting for events

wait :: Event -> IO ()

Block until the event is `set`.

If the state of the event is already "set" this function will return immediately. Otherwise it will block until another thread calls `set`.

(You can also resume a thread that is waiting for an event by throwing an asynchronous exception.)

waitTimeout :: Event -> Integer -> IO Bool

Block until the event is `set` or until a timer expires.

Like `wait`, but with a timeout. A return value of `False` indicates a timeout occurred.

The timeout is specified in microseconds.

If the event is "cleared" and a timeout of 0 μs is specified the function returns `False` without blocking.

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

isSet :: Event -> IO Bool

Returns `True` if the state of the event is "set" and `False` if the state is "cleared".

Notice that this is only a snapshot of the state. By the time a program reacts on its result it may already be out of date.

# Setting events

set :: Event -> IO ()

Changes the state of the event to "set". All threads that where waiting for this event are woken. Threads that `wait` after the state is changed to "set" will not block at all.

signal :: Event -> IO ()

Changes the state to "cleared" after all threads that where waiting for this event are woken. Threads that `wait` after a `signal` will block until the event is `set` again.

The semantics of signal are equivalent to the following definition:

      signal e = mask $ set e >> clear e

clear :: Event -> IO ()

Changes the state of the event to "cleared". Threads that `wait` after the state is changed to "cleared" will block until the state is changed to "set".