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


-- | More useful and humain delaying functions
--   
--   Functions to provide delays, timeouts, and callbacks where the target
--   time is calculated either from a period as an offset from the
--   initialization time, or at a specific <a>UTCTime</a>.
--   
--   Most standard Haskell types are supported for periods, based on the
--   second as the base unit quantity. For more complicated period
--   calculations, <a>Dimensional</a>s <a>Time</a> type is supported.
@package delay
@version 0

module Control.Time

-- | Delay a until at least the specified amount of time has passed.
delay :: (MonadIO m, AsMicro period) => period -> m ()

-- | Delay until a specific <a>UTCTime</a> has occured (at least once).
--   This is slighly confusing, as we can't guarantee we don't return only
--   after the second occurence of the <a>UTCTime</a> under certain leap
--   second handling regimes. Consider for example when <a>delayTill</a> is
--   called during a leap second occurence, where the system clock jumps
--   back and repeats the second. As there is no indication the time has
--   already passed once, we must wait until the second occurence.
delayTill :: (MonadIO m) => UTCTime -> m ()

-- | Run an monad action for at least a specific number of seconds, but not
--   much more.
timeout :: (MonadIO m, MonadMask m, AsMicro period) => period -> m a -> m (Maybe a)

-- | Run a monadic action until it produces a result or a specific time
--   occures. Leap second handling as per delayTill.
timeoutAt :: (MonadIO m, MonadMask m) => UTCTime -> m a -> m (Maybe a)

-- | We hold the CallbackHandle in an MVar so we don't race on
--   update/cancelation and executing the callback. Updating or canceling
--   holds the lock, which is also required to export the action.
type CallbackKey = MVar CallbackHandle

-- | Run a callback after a period of time has passed.
callbackAfter :: (MonadIO m, AsMicro period) => period -> IO () -> m CallbackKey

-- | Run a callback at a specific time.
callbackAt :: MonadIO m => UTCTime -> IO () -> m CallbackKey

-- | Change an existing, unexecuted or canceled callbak to run after a
--   specific period of time from the call of <a>updateCallbackToAfter</a>.
updateCallbackToAfter :: (MonadIO m, AsMicro period) => CallbackKey -> period -> m ()

-- | Change an existing, unexecuted or canceled callbak to run after at a
--   specific time.
updateCallbackTo :: MonadIO m => CallbackKey -> UTCTime -> m ()

-- | Terminate an unexecuted callback.
cancelCallback :: MonadIO m => CallbackKey -> m ()

-- | Calculate the number of microseconds of delay a value represents.
--   Instances must round up for correctness.
class AsMicro d
toMicro :: AsMicro d => d -> Integer
instance GHC.Classes.Eq Control.Time.Timeout
instance GHC.Show.Show Control.Time.Timeout
instance GHC.Exception.Exception Control.Time.Timeout
instance Control.Time.AsMicro Data.Time.Clock.Scale.DiffTime
instance (GHC.Real.Fractional n, Control.Time.AsMicro n) => Control.Time.AsMicro (Numeric.Units.Dimensional.Time n)
instance Control.Time.AsMicro GHC.Integer.Type.Integer
instance Control.Time.AsMicro GHC.Natural.Natural
instance Control.Time.AsMicro GHC.Types.Int
instance Control.Time.AsMicro GHC.Int.Int8
instance Control.Time.AsMicro GHC.Int.Int16
instance Control.Time.AsMicro GHC.Int.Int32
instance Control.Time.AsMicro GHC.Int.Int64
instance Control.Time.AsMicro GHC.Types.Word
instance Control.Time.AsMicro GHC.Word.Word8
instance Control.Time.AsMicro GHC.Word.Word16
instance Control.Time.AsMicro GHC.Word.Word32
instance Control.Time.AsMicro GHC.Word.Word64
instance Control.Time.AsMicro GHC.Types.Float
instance Control.Time.AsMicro GHC.Types.Double
instance Data.Fixed.HasResolution d => Control.Time.AsMicro (Data.Fixed.Fixed d)