Control.Concurrent.Event

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

Each event has an internal 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 ( ... )

Documentation

data Event

An event is in one of two possible states: Set or Cleared.

Instances

Eq Event

Typeable Event

data State

The internal state of an Event. Only interesting when you use the state function.

Constructors

Cleared

Set

Instances

Enum State

Eq State

Ord State

Read State

Show State

Typeable State

new :: IO Event

Create an event. The initial state is Cleared.

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 stop a thread that is waiting for an event by throwing an asynchronous exception.

waitTimeout :: Event -> Int -> 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. A timeout of 0 μs will cause the function to return False without blocking in case the event state is Cleared. Negative timeouts are treated the same as a timeout of 0 μs. The maximum timeout is constrained by the range of the Int type. The Haskell standard guarantees an upper bound of at least 2^29-1 giving a maximum timeout of at least (2^29-1) / 10^6 = ~536 seconds.

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.

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.

state :: Event -> IO State

Determines the current state of the event.

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. This can be avoided by synchronizing access to the event between threads.