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


-- | Retry combinators for monadic actions that may fail
--   
--   This package exposes combinators that can wrap arbitrary monadic
--   actions. They run the action and potentially retry running it with
--   some configurable delay for a configurable number of times. The
--   purpose is to make it easier to work with IO and especially network IO
--   actions that often experience temporary failure and warrant retrying
--   of the original action. For example, a database query may time out for
--   a while, in which case we should hang back for a bit and retry the
--   query instead of simply raising an exception.
@package retry
@version 0.4


-- | This module exposes combinators that can wrap arbitrary monadic
--   actions. They run the action and potentially retry running it with
--   some configurable delay for a configurable number of times.
--   
--   The express purpose of this library is to make it easier to work with
--   IO and especially network IO actions that often experience temporary
--   failure that warrant retrying of the original action. For example, a
--   database query may time out for a while, in which case we should delay
--   a bit and retry the query.
module Control.Retry

-- | Settings for retry behavior. Simply using <a>def</a> for default
--   values should work in most cases.
data RetrySettings
RetrySettings :: RetryLimit -> Bool -> Int -> RetrySettings

-- | Number of retries. Defaults to 5.
numRetries :: RetrySettings -> RetryLimit

-- | Whether to implement exponential backoff in retries. Defaults to True.
backoff :: RetrySettings -> Bool

-- | The base delay in miliseconds. Defaults to 50. Without <a>backoff</a>,
--   this is the delay. With <a>backoff</a>, this base delay will grow by a
--   factor of 2 on each subsequent retry.
baseDelay :: RetrySettings -> Int
data RetryLimit
RLimit :: Int -> RetryLimit
RNoLimit :: RetryLimit

-- | Set a limited number of retries. Default in <a>def</a> is 5.
limitedRetries :: Int -> RetryLimit

-- | Set an unlimited number of retries. Note that with this option turned
--   on, the combinator will keep retrying the action indefinitely and
--   might essentially hang in some cases.
unlimitedRetries :: RetryLimit

-- | Retry combinator for actions that don't raise exceptions, but signal
--   in their type the outcome has failed. Examples are the <a>Maybe</a>,
--   <a>Either</a> and <tt>EitherT</tt> monads.
--   
--   Let's write a function that always fails and watch this combinator
--   retry it 5 additional times following the initial run:
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Maybe
--   
--   &gt;&gt;&gt; let f = putStrLn "Running action" &gt;&gt; return Nothing
--   
--   &gt;&gt;&gt; retrying def isNothing f
--   Running action
--   Running action
--   Running action
--   Running action
--   Running action
--   Running action
--   Nothing
--   </pre>
--   
--   Note how the latest failing result is returned after all retries have
--   been exhausted.
retrying :: MonadIO m => RetrySettings -> (b -> Bool) -> m b -> m b

-- | Run an action and recover from a raised exception by potentially
--   retrying the action a number of times.
recovering :: (MonadIO m, MonadCatch m) => RetrySettings -> [Handler m Bool] -> m a -> m a

-- | Retry ALL exceptions that may be raised. To be used with caution; this
--   matches the exception on <a>SomeException</a>.
--   
--   See how the action below is run once and retried 5 more times before
--   finally failing for good:
--   
--   <pre>
--   &gt;&gt;&gt; let f = putStrLn "Running action" &gt;&gt; error "this is an error"
--   
--   &gt;&gt;&gt; recoverAll def f
--   Running action
--   Running action
--   Running action
--   Running action
--   Running action
--   Running action
--   *** Exception: this is an error
--   </pre>
recoverAll :: (MonadIO m, MonadCatch m) => RetrySettings -> m a -> m a

-- | Delay in micro seconds
delay :: RetrySettings -> Int

-- | Perform <a>threadDelay</a> for the nth retry for the given settings.
performDelay :: MonadIO m => RetrySettings -> Int -> m ()

-- | Delay thread using flat delay
flatDelay :: MonadIO m => RetrySettings -> t -> m ()

-- | Delay thread using backoff delay for the nth retry.
backoffDelay :: MonadIO m => RetrySettings -> Int -> m ()

-- | Delay for nth iteration of exponential backoff, in microseconds
backoffDelayFor :: Int -> Int -> Int
instance Default RetrySettings