concurrent-extra-0.7.0.8: Extra concurrency primitives

MaintainerBas van Dijk <v.dijk.bas@gmail.com> , Roel van Dijk <vandijk.roel@gmail.com>
Safe HaskellSafe

Control.Concurrent.Event

Contents

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

Documentation

data Event Source

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

Instances

Creating events

new :: IO EventSource

Create an event in the "cleared" state.

newSet :: IO EventSource

Create an event in the "set" state.

Waiting for events

wait :: Event -> IO ()Source

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 BoolSource

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 BoolSource

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

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

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 = block $ set e >> clear e

clear :: Event -> IO ()Source

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