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


-- | Timers, timeouts, alarms, monadic wrappers
--   
--   This library provides several timer and timeout related tools:
--   
--   <ul>
--   <li><a>Control.Timeout</a> - Execution of a computation with a time
--   limit, aborting it if the limit is reached before the computation
--   finishes. It is more-or-less a lifted version of <a>System.Timeout</a>
--   from the <tt>base</tt> package. It's good for single use, but it
--   launches a temporary helper thread. If you want to time-limit actions
--   continuously (e.g. if you're implementing a network protocol), you
--   should probably use one of the other tools described below, since they
--   use a single dedicated thread for all the timeouts.</li>
--   <li><a>Control.Timer</a> - Managing a timer running in a dedicated
--   thread. The timer waits for an amount of time you specify, and then
--   runs an action you specify. You can stop and restart it at any
--   time.</li>
--   <li><a>Control.Alarm</a> - Managing an alarm, which is a timer whose
--   action is to notify your thread when the specified amount of time
--   passes.</li>
--   <li><a>Control.Monad.Trans.Timer</a> - A monad transformer for
--   managing a timer</li>
--   <li><a>Control.Monad.Trans.Alarm</a> - A monad transformer for
--   managing an alarm</li>
--   <li><a>Control.Monad.Trans.Timeout</a> - A monad transformer for
--   running actions with timeouts, useful for e.g. network protocols where
--   any send and receive can timeout</li>
--   <li><a>Control.Monad.Timeout.Class</a> - A monad typeclass for running
--   actions with a time limit. <a>Control.Timeout</a> provides a simple
--   trivial for IO (which can then be used with any <tt>MonadIO</tt>), and
--   <a>Control.Monad.Trans.Timeout</a> provides a scalable instance.</li>
--   </ul>
@package time-out
@version 0.2


-- | A typeclass for monads which can run actions with a time limit.
module Control.Monad.Timeout.Class

-- | Timeout exception. Thrown when an action is executed with a time
--   limit, and the time passes before the action finishes.
data Timeout
Timeout :: Timeout

-- | A class for monads capable of executing computations with a time
--   limit. This class provides a uniform interface to the various possible
--   implementations.
--   
--   For example, a trivial implementation may launch a helper thread for
--   each time-limited action. A more scalable implementation, preferred
--   for some cases, may keep a single dedicated thread and reuse it
--   instead of starting new ones.
class (Monad p, Monad m) => MonadTimeout m p

-- | Execute an action with a time limit. If the action finishes before the
--   given time passes, return the value it returned. If the time passes
--   and the action hasn't finished yet, throw a <a>Timeout</a> exception.
timeoutThrow :: (MonadTimeout m p, TimeUnit t) => t -> p a -> m a

-- | Execute an action with a time limit. If the action finishes before the
--   given time passes, return <a>Just</a> the value it returned. If the
--   time passes and the action hasn't finished yet, return <a>Nothing</a>.
timeoutCatch :: (MonadTimeout m p, TimeUnit t) => t -> p a -> m (Maybe a)
instance GHC.Show.Show Control.Monad.Timeout.Class.Timeout
instance GHC.Exception.Exception Control.Monad.Timeout.Class.Timeout

module Control.Timeout

-- | Run a monadic action with a time limit. If it finishes before that
--   time passes and returns value <tt>x</tt>, then <tt>Just x</tt> is
--   returned. If the timeout passes, the action is aborted and
--   <tt>Nothing</tt> is returned. If the action throws an exception, it is
--   aborted and the exception is rethrown.
--   
--   <pre>
--   &gt;&gt;&gt; timeout (3 :: Second) $ delay (1 :: Second) &gt;&gt; return "hello"
--   Just "hello"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; timeout (3 :: Second) $ delay (5 :: Second) &gt;&gt; return "hello"
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; timeout (1 :: Second) $ error "hello"
--   *** Exception: hello
--   </pre>
timeout :: (TimeUnit t, MonadIO m, MonadCatch m) => t -> m a -> m (Maybe a)

-- | Suspend the current thread for the given amount of time.
--   
--   Example:
--   
--   <pre>
--   delay (5 :: Second)
--   </pre>
delay :: (TimeUnit t, MonadIO m) => t -> m ()
instance GHC.Show.Show Control.Timeout.Timeout'
instance GHC.Exception.Exception Control.Timeout.Timeout'
instance Control.Monad.Timeout.Class.MonadTimeout GHC.Types.IO GHC.Types.IO


-- | Manage a timer running in a dedicated thread. You specify an amount of
--   time an and action. The timer waits for that amount of time, and then
--   runs the action. You can stop and restart it at any time.
module Control.Timer
data TimerSettings n
tsDelay :: TimerSettings n -> TimeInterval
tsRun :: TimerSettings n -> n () -> IO ()
tsAction :: TimerSettings n -> n ()
data Timer n
newTimer :: (MonadIO m, MonadIO n, MonadCatch n) => TimerSettings n -> m (Timer n)
releaseTimer :: MonadIO m => Timer n -> m ()
withTimer :: (MonadIO m, MonadMask m, MonadIO n, MonadCatch n) => TimerSettings n -> (Timer n -> m a) -> m a
startTimer :: MonadIO m => Timer n -> m ()
startTimer' :: (TimeUnit t, MonadIO m) => Timer n -> t -> m ()
startTimerWith :: (TimeUnit t, MonadIO m) => Timer n -> Maybe t -> Maybe (n ()) -> m ()
stopTimer :: MonadIO m => Timer n -> m ()
restartTimer :: MonadIO m => Timer n -> m ()
restartTimer' :: (TimeUnit t, MonadIO m) => Timer n -> t -> m ()
restartTimerWith :: (TimeUnit t, MonadIO m) => Timer n -> Maybe t -> Maybe (n ()) -> m ()
instance GHC.Show.Show Control.Timer.StopTimer
instance GHC.Exception.Exception Control.Timer.StopTimer
instance Control.Monad.IO.Class.MonadIO n => Data.Default.Class.Default (Control.Timer.TimerSettings n)


-- | Monad transformer for managing a timer.
module Control.Monad.Trans.Timer
data TimerT n m a
runTimerT :: (MonadIO m, MonadMask m, MonadIO n, MonadCatch n) => TimerT n m a -> TimerSettings n -> m a
startTimer :: MonadIO m => TimerT n m ()
startTimer' :: (MonadIO m, TimeUnit t) => t -> TimerT n m ()
startTimerWith :: (TimeUnit t, MonadIO m) => Maybe t -> Maybe (n ()) -> TimerT n m ()
stopTimer :: MonadIO m => TimerT n m ()
restartTimer :: MonadIO m => TimerT n m ()
restartTimer' :: (TimeUnit t, MonadIO m) => t -> TimerT n m ()
restartTimerWith :: (TimeUnit t, MonadIO m) => Maybe t -> Maybe (n ()) -> TimerT n m ()
instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Control.Monad.Trans.Timer.TimerT n m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.Timer.TimerT n m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Control.Monad.Trans.Timer.TimerT n m)
instance Control.Monad.Trans.Class.MonadTrans (Control.Monad.Trans.Timer.TimerT n)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.Trans.Timer.TimerT n m)
instance Control.Monad.Fix.MonadFix m => Control.Monad.Fix.MonadFix (Control.Monad.Trans.Timer.TimerT n m)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.Trans.Timer.TimerT n m)
instance GHC.Base.Applicative m => GHC.Base.Applicative (Control.Monad.Trans.Timer.TimerT n m)
instance GHC.Base.Functor m => GHC.Base.Functor (Control.Monad.Trans.Timer.TimerT n m)


-- | Manage an alarm clock running in a dedicated thread.
--   
--   You specify an amount of time. The alarm clock waits for that amount
--   of time, and then throws an exception back to you, to notify you the
--   time has passed. You can stop and restart it at any time.
--   
--   This is simply a convenient wrapper over <a>Control.Timer</a>, offered
--   here becuase a common use of timers is to run actions with a time
--   limit (timeout), and the API here makes it more straight-forward to
--   do.
module Control.Alarm
data Alarm
data AlarmWake
newAlarm :: (TimeUnit t, MonadIO m) => t -> m Alarm
releaseAlarm :: MonadIO m => Alarm -> m ()
withAlarm :: (TimeUnit t, MonadIO m, MonadMask m) => t -> (Alarm -> m a) -> m a
startAlarm :: MonadIO m => Alarm -> m ()
startAlarm' :: (TimeUnit t, MonadIO m) => Alarm -> t -> m ()
stopAlarm :: MonadIO m => Alarm -> m ()
restartAlarm :: MonadIO m => Alarm -> m ()
restartAlarm' :: (TimeUnit t, MonadIO m) => Alarm -> t -> m ()
alarm :: (MonadIO m, MonadCatch m) => Alarm -> m a -> m (Maybe a)
alarm' :: (TimeUnit t, MonadIO m, MonadCatch m) => Alarm -> t -> m a -> m (Maybe a)
instance GHC.Show.Show Control.Alarm.AlarmWake
instance GHC.Exception.Exception Control.Alarm.AlarmWake


-- | Monad transformer for managing an alarm clock.
module Control.Monad.Trans.Alarm
data AlarmT m a
runAlarmT :: (TimeUnit t, MonadIO m, MonadMask m) => AlarmT m a -> t -> m a
startAlarm :: MonadIO m => AlarmT m ()
startAlarm' :: (TimeUnit t, MonadIO m) => t -> AlarmT m ()
stopAlarm :: MonadIO m => AlarmT m ()
restartAlarm :: MonadIO m => AlarmT m ()
restartAlarm' :: (TimeUnit t, MonadIO m) => t -> AlarmT m ()
alarm :: (MonadIO m, MonadCatch m) => m a -> AlarmT m (Maybe a)
alarm' :: (TimeUnit t, MonadIO m, MonadCatch m) => t -> m a -> AlarmT m (Maybe a)
instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Control.Monad.Trans.Alarm.AlarmT m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.Alarm.AlarmT m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Control.Monad.Trans.Alarm.AlarmT m)
instance Control.Monad.Trans.Class.MonadTrans Control.Monad.Trans.Alarm.AlarmT
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.Trans.Alarm.AlarmT m)
instance Control.Monad.Fix.MonadFix m => Control.Monad.Fix.MonadFix (Control.Monad.Trans.Alarm.AlarmT m)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.Trans.Alarm.AlarmT m)
instance GHC.Base.Applicative m => GHC.Base.Applicative (Control.Monad.Trans.Alarm.AlarmT m)
instance GHC.Base.Functor m => GHC.Base.Functor (Control.Monad.Trans.Alarm.AlarmT m)


-- | Monad transformer for running actions with a time limit. Provides a
--   scalable <tt>MonadTimeout</tt> instance (at least for the case of a
--   constant number of long-running threads). If you need to use timeouts
--   often in a computation, this is probably better than
--   <a>Control.Timeout</a>.
module Control.Monad.Trans.Timeout

-- | Monad transformer which gives your monad stack an ability to run
--   actions with a timeout, and abort them if they don't finish within the
--   time limit.
--   
--   By default, e.g. if you <a>lift</a> or <a>liftIO</a> an action, it
--   runs in the regular way without a timeout. Use one of the timeout
--   functions, such as <a>withTimeoutThrow</a>, to use the timeout.
data TimeoutT m a
runTimeoutT :: (TimeUnit t, MonadIO m, MonadMask m) => TimeoutT m a -> t -> m a
withTimeoutThrow :: (MonadIO m, MonadCatch m) => m a -> TimeoutT m a
withTimeoutThrow' :: (TimeUnit t, MonadIO m, MonadCatch m) => t -> m a -> TimeoutT m a
withTimeoutCatch :: (MonadIO m, MonadCatch m) => m a -> TimeoutT m (Maybe a)
withTimeoutCatch' :: (TimeUnit t, MonadCatch m, MonadIO m) => t -> m a -> TimeoutT m (Maybe a)
instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Control.Monad.Trans.Timeout.TimeoutT m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Control.Monad.Trans.Timeout.TimeoutT m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Control.Monad.Trans.Timeout.TimeoutT m)
instance Control.Monad.Trans.Class.MonadTrans Control.Monad.Trans.Timeout.TimeoutT
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.Trans.Timeout.TimeoutT m)
instance Control.Monad.Fix.MonadFix m => Control.Monad.Fix.MonadFix (Control.Monad.Trans.Timeout.TimeoutT m)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.Trans.Timeout.TimeoutT m)
instance GHC.Base.Applicative m => GHC.Base.Applicative (Control.Monad.Trans.Timeout.TimeoutT m)
instance GHC.Base.Functor m => GHC.Base.Functor (Control.Monad.Trans.Timeout.TimeoutT m)
instance (Control.Monad.IO.Class.MonadIO m, Control.Monad.Catch.MonadCatch m) => Control.Monad.Timeout.Class.MonadTimeout (Control.Monad.Trans.Timeout.TimeoutT m) m