Dep.SimpleAdvice.Basic

This module contains basic examples advices.

BEWARE! These are provided for illustrative purposes only, they strive for simplicity and not robustness or efficiency.

They can be converted to DepT-based Advices using fromSimple.

Basic advices

returnMempty :: forall ca m r. (Monad m, Monoid r) => Advice ca m r

Makes functions discard their result and always return mempty.

printArgs :: forall m r. MonadIO m => Handle -> String -> Advice Show m r

Given a Handle and a prefix string, makes functions print their arguments to the Handle.

data AnyEq where

A helper datatype for universal equality comparisons of existentialized values, used by doCachingBadly.

For a more complete elaboration of this idea, see the the "exinst" package.

Constructors

AnyEq :: forall a. (Typeable a, Eq a) => a -> AnyEq

Instances

Eq AnyEq

Defined in Dep.SimpleAdvice.Basic

Methods

(==) :: AnyEq -> AnyEq -> Bool

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

doCachingBadly :: forall m r. Monad m => (AnyEq -> m (Maybe r)) -> (AnyEq -> r -> m ()) -> Advice (Eq `And` Typeable) m r

Given the means for looking up and storing r values in the underlying monad m, makes functions (inefficiently) cache their results.

The monad m and the result type r must be known before building the advice. So, once built, this Advice won't be polymorphic over them.

The implementation of this function makes use of the existential type parameter u of makeAdvice, because the phase that processes the function arguments needs to communicate the calculated AnyEq cache key to the phase that processes the function result.

A better implementation of this advice would likely use an AnyHashable helper datatype for the keys.

doAsyncBadly :: forall ca m. MonadUnliftIO m => Advice ca m ()

Makes functions that return () launch asynchronously.

A better implementation of this advice would likely use the "async" package instead of bare forkIO.

injectFailures :: forall ca m r. (MonadIO m, MonadFail m) => IORef ([IO ()], [IO ()]) -> Advice ca m r

Given a reference with two infinite lists of IO actions, on each invocation of the advised function, take an action from the first list and execute it before, and take one action from the second list and execute it after.

A common use for this would be to pass exception-throwing actions.

Synthetic call stacks

type MethodName = String

type StackFrame = (TypeRep, MethodName)

The typeable representation of the record which contains the invoked function, along with the field name of the invoked function.

type SyntheticCallStack = [StackFrame]

data SyntheticCallStackException

Wraps an exception along with a SyntheticCallStack.

Constructors

SyntheticCallStackException SomeException SyntheticCallStack

Instances

Show SyntheticCallStackException

Defined in Dep.SimpleAdvice.Basic

Methods

showsPrec :: Int -> SyntheticCallStackException -> ShowS

show :: SyntheticCallStackException -> String

showList :: [SyntheticCallStackException] -> ShowS

Exception SyntheticCallStackException

Defined in Dep.SimpleAdvice.Basic

Methods

toException :: SyntheticCallStackException -> SomeException

fromException :: SomeException -> Maybe SyntheticCallStackException

displayException :: SyntheticCallStackException -> String

class HasSyntheticCallStack e where

Class of environments that carry a SyntheticCallStack value that can be modified.

Methods

callStack :: forall f. Functor f => (SyntheticCallStack -> f SyntheticCallStack) -> e -> f e

A lens from the environment to the call stack.

Instances

HasSyntheticCallStack SyntheticCallStack

The trivial case, useful when SyntheticCallStack is the environment type of a ReaderT.

Defined in Dep.SimpleAdvice.Basic

Methods

callStack :: Functor f => (SyntheticCallStack -> f SyntheticCallStack) -> SyntheticCallStack -> f SyntheticCallStack

keepCallStack

Arguments

:: (MonadUnliftIO m, MonadReader runenv m, HasSyntheticCallStack runenv, Exception e)

=> (SomeException -> Maybe e)

A selector for the kinds of exceptions we want to catch. For example fromException @IOError.

-> NonEmpty (TypeRep, MethodName)

The path to the current component/method in the environment. Only the head is used. It will be usually obtained through adviseRecord.

-> Advice ca m r

If the environment carries a SyntheticCallStack, make advised functions add themselves to the SyntheticCallStack before they start executing.

This Advice requires a reader-like base monad to work. It doesn't need to be DepT, it can be regular a ReaderT.

Caught exceptions are rethrown wrapped in SyntheticCallStackExceptions, with the current SyntheticCallStack added.