-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Event scheduling system.
--   
--   Allows scheduling and canceling of IO actions to be executed at a
--   specified future time.
@package control-event
@version 0.2


-- | This module can execute events at specified time. It uses a two thread
--   system that allows the STM adding and deleting of new threads without
--   requiring later IO actions. An ability to place arbitrary event
--   preprocessing when adding each event exists, but in a course grained
--   manner. This feature can be expanded on request.
--   
--   This is very like control-timeout, but was developed separately
--   internal operation is similar with a thread sleeping via threadDelay
--   and EventIds being based in part on expire time. It differs in that
--   control-event is: * More complex * Requires initilization * Allows
--   pure STM adding and removing of events (no post STM IO action) *
--   Allows user control over event systems (can have more than one) *
--   Allows events to run in event handler thread (advisable if thread
--   spark is too expensive / computation is cheap) * No possible
--   duplication of EventId (theoretical! no real advantage)
--   
--   On the other hand, a shim could be made to provide the control-timeout
--   API with Control.Event running under the hood.
module Control.Event

-- | IDs the program can use to cancel previously scheduled events.
data EventId

-- | A value indicating there is no such event.
--   
--   The event system can either be initilized and passed as state or a
--   global system can be declared using gEvtSys = unsafePeformIO
--   initEventSystem
data EventSystem
noEvent :: EventId

-- | The only way to get an event system is to initilize one, which sets
--   internal TVars and sparks two threads (one to expire events, one to
--   look if you've added an event expiring before the current alarm).
initEventSystem :: IO EventSystem

-- | Add an *action* to be performed at *time* by *system*, returning a
--   unique id.
addEvent :: EventSystem -> ClockTime -> IO () -> IO EventId

-- | Atomically add an action to be performed at specified time and
--   returning a unique id.
addEventSTM :: EventSystem -> ClockTime -> IO () -> STM EventId

-- | Cancel an event from the system, returning True on success.
cancelEvent :: EventSystem -> EventId -> IO Bool

-- | Atomically cancel an event from the system, returning True on success.
cancelEventSTM :: EventSystem -> EventId -> STM Bool
evtSystemSize :: EventSystem -> STM Int
instance Typeable TimerReset
instance Eq TimerReset
instance Ord TimerReset
instance Show TimerReset
instance Eq EventId
instance Ord EventId
instance Show EventId


-- | This module is a shim, providing the control-timeout api using
--   control-event to run the show
module Control.Event.Timeout
addTimeout :: Float -> (IO ()) -> IO TimeoutTag
addTimeoutAtomic :: Float -> IO () -> IO (STM TimeoutTag)
cancelTimeout :: TimeoutTag -> STM Bool
data TimeoutTag