-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Extra concurrency primitives -- -- Offers a selection of synchronization primitives: -- -- -- -- Please consult the API documentation of the individual modules for -- more detailed information. -- -- Inspired by the concurrency libraries of Java and Python. @package concurrent-extra @version 0.1 -- | This module provides the Lock synchronization mechanism. It was -- inspired by the Python and Java Lock objects and should -- behave in a similar way. See: -- -- http://docs.python.org/3.1/library/threading.html#lock-objects -- -- and: -- -- -- http://java.sun.com/javase/7/docs/api/java/util/concurrent/locks/Lock.html -- -- All functions are exception safe. Throwing asynchronous -- exceptions will not compromise the internal state of a Lock. -- -- This module is intended to be imported qualified. We suggest importing -- it like: -- -- 
--   import           Control.Concurrent.Lock         ( Lock )
--   import qualified Control.Concurrent.Lock as Lock ( ... )
--
module Control.Concurrent.Lock -- | A lock is in one of two states, "locked" or "unlocked". data Lock -- | Create an unlocked lock. new :: IO Lock -- | Create a locked lock. newAcquired :: IO Lock -- | When the state is unlocked, acquire changes the state to -- locked and returns immediately. When the state is locked, -- acquire blocks until a call to release in another -- thread changes it to unlocked, then the acquire call resets -- it to locked and returns. -- -- There are two further important properties of acquire: -- -- acquire :: Lock -> IO () -- | A non-blocking acquire. When the state is unlocked, -- tryAcquire changes the state to locked and returns -- immediately with True. When the state is locked, -- tryAcquire leaves the state unchanged and returns immediately -- with False. tryAcquire :: Lock -> IO Bool -- | release changes the state to unlocked and returns -- immediately. -- -- Note that it is an error to release an unlocked lock! -- -- If there are any threads blocked on acquire the thread that -- first called acquire will be woken up. release :: Lock -> IO () -- | A convenience function which first acquires the lock and then performs -- the computation. When the computation terminates, whether normally or -- by raising an exception, the lock is released. -- -- Note that: with = liftA2 bracket_ acquire -- release. with :: Lock -> IO a -> IO a -- | A non-blocking with. tryWith is a convenience function -- which first tries to acquire the lock. If that fails, Nothing -- is returned. If it succeeds, the computation is performed. When the -- computation terminates, whether normally or by raising an exception, -- the lock is released and Just the result of the computation is -- returned. tryWith :: Lock -> IO α -> IO (Maybe α) -- | Determines if the lock is in the locked state. -- -- 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. locked :: Lock -> IO Bool instance Typeable Lock instance Eq Lock -- | This module provides the RLock synchronization mechanism. It -- was inspired by the Python RLock and Java -- ReentrantLock objects and should behave in a similar way. -- See: -- -- http://docs.python.org/3.1/library/threading.html#rlock-objects -- -- and: -- -- -- http://java.sun.com/javase/7/docs/api/java/util/concurrent/locks/ReentrantLock.html -- -- All functions are exception safe. Throwing asynchronous -- exceptions will not compromise the internal state of a RLock. -- -- This module is intended to be imported qualified. We suggest importing -- it like: -- -- 
--   import           Control.Concurrent.RLock          ( RLock )
--   import qualified Control.Concurrent.RLock as RLock ( ... )
--
module Control.Concurrent.RLock data RLock new :: IO RLock newAcquired :: IO RLock acquire :: RLock -> IO () tryAcquire :: RLock -> IO Bool release :: RLock -> IO () with :: RLock -> IO α -> IO α tryWith :: RLock -> IO α -> IO (Maybe α) recursionLevel :: RLock -> IO Integer instance Typeable RLock instance Eq RLock -- | 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 ( ... )
--
module Control.Concurrent.Event -- | An event is in one of two possible states: Set or -- Cleared. data Event -- | The internal state of an Event. Only interesting when you use -- the state function. data State Cleared :: State Set :: State -- | Create an event. The initial state is Cleared. new :: IO Event -- | 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. wait :: Event -> IO () -- | 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. waitTimeout :: Event -> Int -> IO Bool -- | 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. set :: 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. clear :: Event -> IO () -- | 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. state :: Event -> IO State instance Typeable State instance Typeable Event instance Enum State instance Eq State instance Ord State instance Show State instance Read State instance Eq 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.STM.Event          ( Event )
--   import qualified Control.Concurrent.STM.Event as Event ( ... )
--
module Control.Concurrent.STM.Event -- | An event is in one of two possible states: Set or -- Cleared. data Event -- | The internal state of an Event. Only interesting when you use -- the state function. data State Cleared :: State Set :: State -- | Create an event. The initial state is Cleared. new :: STM Event -- | Retry until the event is set. -- -- If the state of the event is already Set this function will -- return immediately. Otherwise it will retry until another thread calls -- set. -- -- You can also stop a thread that is waiting for an event by throwing an -- asynchronous exception. wait :: Event -> STM () -- | 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 retry. set :: Event -> STM () -- | Changes the state of the event to Cleared. Threads that -- wait after the state is changed to Cleared will retry -- until the state is changed to Set. clear :: Event -> STM () -- | The current state of the event. state :: Event -> STM State instance Typeable Event instance Eq Event -- | Multiple-reader, single-writer locks. Used to protect shared resources -- which may be concurrently read, but only sequentially written. -- -- All functions are exception safe. Throwing asynchronous -- exceptions will not compromise the internal state of an RWLock. -- This means it is perfectly safe to kill a thread that is blocking on, -- for example, acquireRead. -- -- See also Java's version: -- http://java.sun.com/javase/7/docs/api/java/util/concurrent/locks/ReadWriteLock.html -- -- This module is designed to be imported qualified. We suggest importing -- it like: -- -- 
--   import           Control.Concurrent.ReadWriteLock        ( RWLock )
--   import qualified Control.Concurrent.ReadWriteLock as RWL ( ... )
--
module Control.Concurrent.ReadWriteLock -- | Multiple-reader, single-writer lock. Is in one of three states: -- -- data RWLock -- | Create a new RWLock. The initial state is "free"; either read -- or write access can be acquired without blocking. new :: IO RWLock -- | Acquire the read lock. -- -- Blocks if another thread has acquired write access. If -- acquireRead terminates without throwing an exception the -- state of the RWLock will be "read". -- -- Implementation note: Throws an exception when more than (maxBound :: -- Int) simultaneous threads acquire the read lock. But that is unlikely. acquireRead :: RWLock -> IO () -- | Release the read lock. -- -- If the calling thread was the last one to relinquish read access the -- state will revert to "free". -- -- It is an error to release read access to an RWLock which is not -- in the "read" state. releaseRead :: RWLock -> IO () -- | A convenience function wich first acquires read access and then -- performs the computation. When the computation terminates, whether -- normally or by raising an exception, the read lock is released. withRead :: RWLock -> IO α -> IO α -- | Try to acquire the read lock; non blocking. -- -- Like acquireRead, but doesn't block. Returns True if the -- resulting state is "read", False otherwise. tryAcquireRead :: RWLock -> IO Bool -- | A non-blocking withRead. First tries to acquire the lock. If -- that fails, Nothing is returned. If it succeeds, the -- computation is performed. When the computation terminates, whether -- normally or by raising an exception, the lock is released and -- Just the result of the computation is returned. tryWithRead :: RWLock -> IO α -> IO (Maybe α) -- | Acquire the write lock. -- -- Blocks if another thread has acquired either read or write access. If -- acquireWrite terminates without throwing an exception the -- state of the RWLock will be "write". acquireWrite :: RWLock -> IO () -- | Release the write lock. -- -- If releaseWrite terminates without throwing an exception the -- state will be "free". -- -- It is an error to release write access to an RWLock which is -- not in the "write" state. releaseWrite :: RWLock -> IO () -- | A convenience function wich first acquires write access and then -- performs the computation. When the computation terminates, whether -- normally or by raising an exception, the write lock is released. withWrite :: RWLock -> IO α -> IO α -- | Try to acquire the write lock; non blocking. -- -- Like acquireWrite, but doesn't block. Returns True if -- the resulting state is "write", False otherwise. tryAcquireWrite :: RWLock -> IO Bool -- | A non-blocking withWrite. First tries to acquire the lock. If -- that fails, Nothing is returned. If it succeeds, the -- computation is performed. When the computation terminates, whether -- normally or by raising an exception, the lock is released and -- Just the result of the computation is returned. tryWithWrite :: RWLock -> IO α -> IO (Maybe α) instance Typeable RWLock instance Eq RWLock -- | Concurrent read, sequential write variables. Comparable to an -- IORef with more advanced synchronization mechanisms. The value -- stored inside the RWVar can be read and used by multiple -- threads at the same time. Concurrent computations inside a with -- "block" observe the same value. -- -- Observing and changing the contents of an RWVar are mutually -- exclusive. The with function will block if modify is -- active and vice-versa. Furthermore with is fully sequential and -- will also block on concurrent calls of with. -- -- The following are guaranteed deadlocks: -- -- -- -- All functions are exception safe. Throwing asynchronous -- exceptions will not compromise the internal state of an RWVar. -- This also means that threads blocking on with or modify -- and friends can still be unblocked by throwing an asynchronous -- exception. -- -- This module is designed to be imported qualified. We suggest importing -- it like: -- -- 
--   import           Control.Concurrent.ReadWriteVar        ( RWVar )
--   import qualified Control.Concurrent.ReadWriteVar as RWV ( ... )
--
module Control.Concurrent.ReadWriteVar -- | Concurrently readable and sequentially writable variable. data RWVar α -- | Create a new RWVar. new :: α -> IO (RWVar α) -- | Execute an action that operates on the contents of the RWVar. -- -- The action is guaranteed to have a consistent view of the stored -- value. Any function that attempts to modify the contents will -- block until the action is completed. -- -- If another thread is modifying the contents of the RWVar this -- function will block until the other thread finishes its action. with :: RWVar α -> (α -> IO β) -> IO β -- | Like with but doesn't block. Returns Just the result if -- read access could be acquired without blocking, Nothing -- otherwise. tryWith :: RWVar α -> (α -> IO β) -> IO (Maybe β) -- | Modify the contents of an RWVar. -- -- This function needs exclusive write access to the RWVar. Only -- one thread can modify an RWVar at the same time. All others -- will block. modify_ :: RWVar α -> (α -> IO α) -> IO () -- | Modify the contents of an RWVar and return an additional value. -- -- Like modify_, but allows a value to be returned (β) in addition -- to the modified value of the RWVar. modify :: RWVar α -> (α -> IO (α, β)) -> IO β -- | Attempt to modify the contents of an RWVar. -- -- Like modify_, but doesn't block. Returns True if the -- contents could be replaced, False otherwise. tryModify_ :: RWVar α -> (α -> IO α) -> IO Bool -- | Attempt to modify the contents of an RWVar and return an -- additional value. -- -- Like modify, but doesn't block. Returns Just the -- additional value if the contents could be replaced, Nothing -- otherwise. tryModify :: RWVar α -> (α -> IO (α, β)) -> IO (Maybe β) instance Typeable1 RWVar instance Eq (RWVar α)