Effectful.Retry

This module provides a Retry effect to adapt the retry library for the effectful ecosystem.

Effect

data Retry :: Effect

An empty effect to provide the retry requirements, e.g. MonadIO and MonadMask

Instances

type DispatchOf Retry

Defined in Effectful.Retry

type DispatchOf Retry = 'Static 'WithSideEffects

data StaticRep Retry

Defined in Effectful.Retry

data StaticRep Retry = Retry

runRetry :: IOE :> es => Eff (Retry ': es) a -> Eff es a

Peel the Retry effect.

Types and Operations

newtype RetryPolicyM (m :: Type -> Type)

A RetryPolicyM is a function that takes an RetryStatus and possibly returns a delay in microseconds. Iteration numbers start at zero and increase by one on each retry. A *Nothing* return value from the function implies we have reached the retry limit.

Please note that RetryPolicyM is a Monoid. You can collapse multiple strategies into one using mappend or <>. The semantics of this combination are as follows:

1. If either policy returns Nothing, the combined policy returns Nothing. This can be used to inhibit after a number of retries, for example.
2. If both policies return a delay, the larger delay will be used. This is quite natural when combining multiple policies to achieve a certain effect.

Example:

One can easily define an exponential backoff policy with a limited number of retries:

> limitedBackoff = exponentialBackoff 50000 <> limitRetries 5

Naturally, mempty will retry immediately (delay 0) for an unlimited number of retries, forming the identity for the Monoid.

The default retry policy retryPolicyDefault implements a constant 50ms delay, up to 5 times:

> retryPolicyDefault = constantDelay 50000 <> limitRetries 5

For anything more complex, just define your own RetryPolicyM:

> myPolicy = retryPolicy $ \ rs -> if rsIterNumber rs > 10 then Just 1000 else Just 10000

Since 0.7.

Constructors

RetryPolicyM

Fields

• getRetryPolicyM :: RetryStatus -> m (Maybe Int)

Instances

Monad m => Monoid (RetryPolicyM m)

Defined in Control.Retry

Methods

mempty :: RetryPolicyM m

mappend :: RetryPolicyM m -> RetryPolicyM m -> RetryPolicyM m

mconcat :: [RetryPolicyM m] -> RetryPolicyM m

Monad m => Semigroup (RetryPolicyM m)

Defined in Control.Retry

Methods

(<>) :: RetryPolicyM m -> RetryPolicyM m -> RetryPolicyM m

sconcat :: NonEmpty (RetryPolicyM m) -> RetryPolicyM m

stimes :: Integral b => b -> RetryPolicyM m -> RetryPolicyM m

retryPolicy :: forall (m :: Type -> Type). Monad m => (RetryStatus -> Maybe Int) -> RetryPolicyM m

Helper for making simplified policies that don't use the monadic context.

retryPolicyDefault :: forall (m :: Type -> Type). Monad m => RetryPolicyM m

Default retry policy

data RetryAction

How to handle a failed action.

Constructors

DontRetry

Don't retry (regardless of what the RetryPolicy says).

ConsultPolicy

Retry if the RetryPolicy says so, with the delay specified by the policy.

ConsultPolicyOverrideDelay Int

Retry if the RetryPolicy says so, but override the policy's delay (number of microseconds).

Instances

Generic RetryAction

Defined in Control.Retry

Associated Types

type Rep RetryAction :: Type -> Type

Methods

from :: RetryAction -> Rep RetryAction x

to :: Rep RetryAction x -> RetryAction

Read RetryAction

Defined in Control.Retry

Methods

readsPrec :: Int -> ReadS RetryAction

readList :: ReadS [RetryAction]

readPrec :: ReadPrec RetryAction

readListPrec :: ReadPrec [RetryAction]

Show RetryAction

Defined in Control.Retry

Methods

showsPrec :: Int -> RetryAction -> ShowS

show :: RetryAction -> String

showList :: [RetryAction] -> ShowS

Eq RetryAction

Defined in Control.Retry

Methods

(==) :: RetryAction -> RetryAction -> Bool

(/=) :: RetryAction -> RetryAction -> Bool

type Rep RetryAction

Defined in Control.Retry

type Rep RetryAction = D1 ('MetaData "RetryAction" "Control.Retry" "retry-0.9.3.0-BQnGInPtbrV6DNdCGLsy4a" 'False) (C1 ('MetaCons "DontRetry" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "ConsultPolicy" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "ConsultPolicyOverrideDelay" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Int))))

toRetryAction :: Bool -> RetryAction

Convert a boolean answer to the question "Should we retry?" into a RetryAction.

data RetryStatus

Datatype with stats about retries made thus far.

Constructors

RetryStatus

Fields

• rsIterNumber :: !Int

  Iteration number, where 0 is the first try

• rsCumulativeDelay :: !Int

  Delay incurred so far from retries in microseconds

• rsPreviousDelay :: !(Maybe Int)

  Latest attempt's delay. Will always be Nothing on first run.

Instances

Generic RetryStatus

Defined in Control.Retry

Associated Types

type Rep RetryStatus :: Type -> Type

Methods

from :: RetryStatus -> Rep RetryStatus x

to :: Rep RetryStatus x -> RetryStatus

Read RetryStatus

Defined in Control.Retry

Methods

readsPrec :: Int -> ReadS RetryStatus

readList :: ReadS [RetryStatus]

readPrec :: ReadPrec RetryStatus

readListPrec :: ReadPrec [RetryStatus]

Show RetryStatus

Defined in Control.Retry

Methods

showsPrec :: Int -> RetryStatus -> ShowS

show :: RetryStatus -> String

showList :: [RetryStatus] -> ShowS

Eq RetryStatus

Defined in Control.Retry

Methods

(==) :: RetryStatus -> RetryStatus -> Bool

(/=) :: RetryStatus -> RetryStatus -> Bool

type Rep RetryStatus

Defined in Control.Retry

type Rep RetryStatus = D1 ('MetaData "RetryStatus" "Control.Retry" "retry-0.9.3.0-BQnGInPtbrV6DNdCGLsy4a" 'False) (C1 ('MetaCons "RetryStatus" 'PrefixI 'True) (S1 ('MetaSel ('Just "rsIterNumber") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int) :*: (S1 ('MetaSel ('Just "rsCumulativeDelay") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int) :*: S1 ('MetaSel ('Just "rsPreviousDelay") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (Maybe Int)))))

defaultRetryStatus :: RetryStatus

Initial, default retry status. Use fields or lenses to update.

applyPolicy :: Retry :> es => RetryPolicyM (Eff es) -> RetryStatus -> Eff es (Maybe RetryStatus)

applyAndDelay :: Retry :> es => RetryPolicyM (Eff es) -> RetryStatus -> Eff es (Maybe RetryStatus)

Applying Retry Policies

retrying :: Retry :> es => RetryPolicyM (Eff es) -> (RetryStatus -> b -> Eff es Bool) -> (RetryStatus -> Eff es b) -> Eff es b

retryingDynamic :: Retry :> es => RetryPolicyM (Eff es) -> (RetryStatus -> b -> Eff es RetryAction) -> (RetryStatus -> Eff es b) -> Eff es b

recovering :: Retry :> es => RetryPolicyM (Eff es) -> [RetryStatus -> Handler (Eff es) Bool] -> (RetryStatus -> Eff es a) -> Eff es a

recoveringDynamic :: Retry :> es => RetryPolicyM (Eff es) -> [RetryStatus -> Handler (Eff es) RetryAction] -> (RetryStatus -> Eff es a) -> Eff es a

stepping :: Retry :> es => RetryPolicyM (Eff es) -> [RetryStatus -> Handler (Eff es) Bool] -> (RetryStatus -> Eff es ()) -> (RetryStatus -> Eff es a) -> RetryStatus -> Eff es (Maybe a)

recoverAll :: Retry :> es => RetryPolicyM (Eff es) -> (RetryStatus -> Eff es a) -> Eff es a

skipAsyncExceptions :: Retry :> es => [RetryStatus -> Handler (Eff es) Bool]

logRetries :: (Retry :> es, Exception e) => (e -> Eff es Bool) -> (Bool -> e -> RetryStatus -> Eff es ()) -> RetryStatus -> Handler (Eff es) Bool

defaultLogMsg :: Exception e => Bool -> e -> RetryStatus -> String

For use with logRetries.

Resumable variants

resumeRetrying :: Retry :> es => RetryStatus -> RetryPolicyM (Eff es) -> (RetryStatus -> b -> Eff es Bool) -> (RetryStatus -> Eff es b) -> Eff es b

resumeRetryingDynamic :: Retry :> es => RetryStatus -> RetryPolicyM (Eff es) -> (RetryStatus -> b -> Eff es RetryAction) -> (RetryStatus -> Eff es b) -> Eff es b

resumeRecovering :: Retry :> es => RetryStatus -> RetryPolicyM (Eff es) -> [RetryStatus -> Handler (Eff es) Bool] -> (RetryStatus -> Eff es a) -> Eff es a

resumeRecoveringDynamic :: Retry :> es => RetryStatus -> RetryPolicyM (Eff es) -> [RetryStatus -> Handler (Eff es) RetryAction] -> (RetryStatus -> Eff es a) -> Eff es a

resumeRecoverAll :: Retry :> es => RetryStatus -> RetryPolicyM (Eff es) -> (RetryStatus -> Eff es a) -> Eff es a

Retry Policies

constantDelay

Arguments

:: forall (m :: Type -> Type). Monad m

=> Int

Base delay in microseconds

-> RetryPolicyM m

Implement a constant delay with unlimited retries.

exponentialBackoff

Arguments

:: forall (m :: Type -> Type). Monad m

=> Int

Base delay in microseconds

-> RetryPolicyM m

Grow delay exponentially each iteration. Each delay will increase by a factor of two.

fullJitterBackoff

Arguments

:: forall (m :: Type -> Type). MonadIO m

=> Int

Base delay in microseconds

-> RetryPolicyM m

FullJitter exponential backoff as explained in AWS Architecture Blog article.

http://www.awsarchitectureblog.com/2015/03/backoff.html

temp = min(cap, base * 2 ** attempt)

sleep = temp / 2 + random_between(0, temp / 2)

fibonacciBackoff

Arguments

:: forall (m :: Type -> Type). Monad m

=> Int

Base delay in microseconds

-> RetryPolicyM m

Implement Fibonacci backoff.

limitRetries

Arguments

:: Int

Maximum number of retries.

-> RetryPolicy

Retry immediately, but only up to n times.

Policy Transformers

limitRetriesByDelay

Arguments

:: forall (m :: Type -> Type). Monad m

=> Int

Time-delay limit in microseconds.

-> RetryPolicyM m

-> RetryPolicyM m

Add an upperbound to a policy such that once the given time-delay amount *per try* has been reached or exceeded, the policy will stop retrying and fail. If you need to stop retrying once *cumulative* delay reaches a time-delay amount, use limitRetriesByCumulativeDelay

limitRetriesByCumulativeDelay

Arguments

:: forall (m :: Type -> Type). Monad m

=> Int

Time-delay limit in microseconds.

-> RetryPolicyM m

-> RetryPolicyM m

Add an upperbound to a policy such that once the cumulative delay over all retries has reached or exceeded the given limit, the policy will stop retrying and fail.

capDelay

Arguments

:: forall (m :: Type -> Type). Monad m

=> Int

A maximum delay in microseconds

-> RetryPolicyM m

-> RetryPolicyM m

Set a time-upperbound for any delays that may be directed by the given policy. This function does not terminate the retrying. The policy `capDelay maxDelay (exponentialBackoff n)` will never stop retrying. It will reach a state where it retries forever with a delay of maxDelay between each one. To get termination you need to use one of the limitRetries function variants.

Development Helpers

simulatePolicy :: Monad m => Int -> RetryPolicyM m -> m [(Int, Maybe Int)]

Run given policy up to N iterations and gather results. In the pair, the Int is the iteration number and the Maybe Int is the delay in microseconds.

simulatePolicyPP :: Int -> RetryPolicyM IO -> IO ()

Run given policy up to N iterations and pretty print results on the console.