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


-- | Wake up and perform an action at a certain time.
--   
--   Please see the README on Bitbucket at
--   <a>https://bitbucket.org/davecturner/alarmclock#readme</a>
@package alarmclock
@version 0.6.0.2


-- | Abstraction that allows for a choice of timescale when setting alarms.
--   Exposed in a separate module so it can be faked for testing purposes,
--   but client applications should just import
--   <a>Control.Concurrent.AlarmClock</a>.
module Control.Concurrent.AlarmClock.TimeScale

-- | Abstraction that allows for a choice between the UTC timescale and a
--   monotonic timescale, which differ in their handling of irregularities
--   such as clock adjustments and leap seconds.
--   
--   Alarms set using the <a>UTCTime</a> timescale wait for the system
--   clock to pass the given time before going off, and account for the
--   clock being adjusted backwards and for (positive) leap seconds while
--   waiting. If the clock is set forwards, or a negative leap second
--   occurs, then the alarm may go off later than expected by an amount
--   that is roughly equal to the adjustment. It is possible to correct for
--   this by setting the alarm again after the adjustment has occurred.
--   
--   The <a>Monotonic</a> timescale cannot be so adjusted, which may be
--   more suitable for some applications.
--   
--   Note that the timeliness of the alarm going off is very much on a
--   "best effort" basis, and there are many environmental factors that
--   could cause the alarm to go off later than expected.
class Eq t => TimeScale t
getAbsoluteTime :: TimeScale t => IO t
microsecondsDiff :: TimeScale t => t -> t -> Integer
earlierOf :: TimeScale t => t -> t -> t

-- | Representation of system monotonic clock.
newtype MonotonicTime
MonotonicTime :: TimeSpec -> MonotonicTime
instance GHC.Classes.Ord Control.Concurrent.AlarmClock.TimeScale.MonotonicTime
instance GHC.Classes.Eq Control.Concurrent.AlarmClock.TimeScale.MonotonicTime
instance GHC.Show.Show Control.Concurrent.AlarmClock.TimeScale.MonotonicTime
instance Control.Concurrent.AlarmClock.TimeScale.TimeScale Control.Concurrent.AlarmClock.TimeScale.MonotonicTime
instance Control.Concurrent.AlarmClock.TimeScale.TimeScale Data.Time.Clock.Internal.UTCTime.UTCTime


-- | Device for running an action at (i.e. shortly after) a certain time,
--   which can be used to implement things like time-based cache expiry.
--   
--   This implementation avoids the use of polling and leans on Haskell's
--   scheduler to achieve low-latency without lots of computational
--   overhead.
--   
--   The alarm can be set multiple times, and in this case the alarm will
--   go off at the earliest requested time. If the alarm is set in the
--   past, the action will run immediately. When the action runs, it clears
--   all future alarms; the action can itself set the next alarm time.
--   
--   To perform time-based cache expiry, create an <a>AlarmClock</a> whose
--   action flushes any stale entries from the cache and then calls
--   <a>setAlarm</a> for the next time that an entry will expire (if there
--   are any). When expiring entries are added to the cache, call
--   <a>setAlarm</a> to ensure that they will expire in a timely fashion.
module Control.Concurrent.AlarmClock

-- | An <a>AlarmClock</a> is a device for running an action at (or shortly
--   after) a certain time.
data AlarmClock t

-- | Create a new <a>AlarmClock</a> that runs the given action. Initially,
--   there is no wakeup time set: you must call <a>setAlarm</a> for
--   anything else to happen.
newAlarmClock :: TimeScale t => (AlarmClock t -> IO ()) -> IO (AlarmClock t)

-- | Create a new <a>AlarmClock</a> that runs the given action. Initially,
--   there is no wakeup time set: you must call <a>setAlarm</a> for
--   anything else to happen.
newAlarmClock' :: TimeScale t => (AlarmClock t -> t -> IO ()) -> IO (AlarmClock t)

-- | Destroy the <a>AlarmClock</a> so no further alarms will occur. If the
--   alarm is currently going off then this will block until the action is
--   finished.
destroyAlarmClock :: AlarmClock t -> IO ()

-- | The action <tt>withAlarmClock onWakeUp inner</tt> runs <tt>inner</tt>
--   with a new <a>AlarmClock</a> which is destroyed when <tt>inner</tt>
--   exits.
withAlarmClock :: TimeScale t => (AlarmClock t -> t -> IO ()) -> (AlarmClock t -> IO a) -> IO a

-- | Make the <a>AlarmClock</a> go off at (or shortly after) the given
--   time. This can be called more than once; in which case, the alarm will
--   go off at the earliest given time.
setAlarm :: TimeScale t => AlarmClock t -> t -> IO ()

-- | Make the <a>AlarmClock</a> go off at (or shortly after) the given
--   time. This can be called more than once; in which case, the alarm will
--   go off at the earliest given time.
setAlarmSTM :: TimeScale t => AlarmClock t -> t -> STM ()

-- | Make the <a>AlarmClock</a> go off right now.
setAlarmNow :: TimeScale t => AlarmClock t -> IO ()

-- | Is the alarm set - i.e. will it go off at some point in the future
--   even if <a>setAlarm</a> is not called?
isAlarmSet :: AlarmClock t -> IO Bool

-- | Is the alarm set - i.e. will it go off at some point in the future
--   even if <a>setAlarm</a> is not called?
isAlarmSetSTM :: AlarmClock t -> STM Bool

-- | Abstraction that allows for a choice between the UTC timescale and a
--   monotonic timescale, which differ in their handling of irregularities
--   such as clock adjustments and leap seconds.
--   
--   Alarms set using the <a>UTCTime</a> timescale wait for the system
--   clock to pass the given time before going off, and account for the
--   clock being adjusted backwards and for (positive) leap seconds while
--   waiting. If the clock is set forwards, or a negative leap second
--   occurs, then the alarm may go off later than expected by an amount
--   that is roughly equal to the adjustment. It is possible to correct for
--   this by setting the alarm again after the adjustment has occurred.
--   
--   The <a>Monotonic</a> timescale cannot be so adjusted, which may be
--   more suitable for some applications.
--   
--   Note that the timeliness of the alarm going off is very much on a
--   "best effort" basis, and there are many environmental factors that
--   could cause the alarm to go off later than expected.
class Eq t => TimeScale t

-- | Representation of system monotonic clock.
newtype MonotonicTime
MonotonicTime :: TimeSpec -> MonotonicTime
