Control.Monad.Component

Provides functions that help on the creation of Application teardown sub-routines

ComponentM monad and runner

data ComponentM a

ComponentM is a wrapper of the IO monad that automatically deals with the composition of Teardown sub-routines from resources allocated in every resource of your application. To build ComponentM actions see the buildComponent, buildComponentWithCleanup and buildComponentWithTeardown functions.

Instances

Monad ComponentM

Methods

(>>=) :: ComponentM a -> (a -> ComponentM b) -> ComponentM b

(>>) :: ComponentM a -> ComponentM b -> ComponentM b

return :: a -> ComponentM a

fail :: String -> ComponentM a

Functor ComponentM

Methods

fmap :: (a -> b) -> ComponentM a -> ComponentM b

(<$) :: a -> ComponentM b -> ComponentM a

MonadFail ComponentM

Methods

fail :: String -> ComponentM a

Applicative ComponentM

Methods

pure :: a -> ComponentM a

(<*>) :: ComponentM (a -> b) -> ComponentM a -> ComponentM b

(*>) :: ComponentM a -> ComponentM b -> ComponentM b

(<*) :: ComponentM a -> ComponentM b -> ComponentM a

MonadIO ComponentM

Methods

liftIO :: IO a -> ComponentM a

MonadThrow ComponentM

Methods

throwM :: Exception e => e -> ComponentM a

runComponentM :: Text -> ComponentM a -> IO (Component a)

Given the name and a ComponentM sub-routine, this function builds an IO sub-routine that returns a Component record.

The name argument is used for trace-ability purposes when executing the teardown of a resulting Component.

• A note on error scenarios:

Sometimes the given ComponentM sub-routine may fail on execution, in such cases, this function will teardown all component resources allocated so far and throw a ComponentStartupFailure exception.

Component record and functions

data Component a

Represents the result of a ComponentM sub-routine, it contains a resource record which can be recovered using fromComponent and a Teardown sub-routine that can be executed using the teardown function.

Instances

Generic (Component a)

Associated Types

type Rep (Component a) :: * -> *

Methods

from :: Component a -> Rep (Component a) x

to :: Rep (Component a) x -> Component a

NFData a => NFData (Component a)

Methods

rnf :: Component a -> ()

ITeardown (Component a)

Methods

teardown :: Component a -> IO TeardownResult

type Rep (Component a)

type Rep (Component a) = D1 (MetaData "Component" "Control.Monad.Component.Internal.Types" "teardown-0.3.0.0-LZiK4LTLuZAIXZzqo3R66V" False) (C1 (MetaCons "Component" PrefixI True) ((:*:) (S1 (MetaSel (Just Symbol "componentResource") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 a)) (S1 (MetaSel (Just Symbol "componentTeardown") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Teardown))))

fromComponent :: Component a -> a

Fetches the resource of a Component returned by a ComponentM sub-routine.

Component error record

data ComponentError

Constructors

ComponentFailure !Text

ComponentStartupFailure ![SomeException]

Instances

Show ComponentError

Methods

showsPrec :: Int -> ComponentError -> ShowS

show :: ComponentError -> String

showList :: [ComponentError] -> ShowS

Generic ComponentError

Associated Types

type Rep ComponentError :: * -> *

Methods

from :: ComponentError -> Rep ComponentError x

to :: Rep ComponentError x -> ComponentError

Exception ComponentError

Methods

toException :: ComponentError -> SomeException

fromException :: SomeException -> Maybe ComponentError

displayException :: ComponentError -> String

type Rep ComponentError

type Rep ComponentError = D1 (MetaData "ComponentError" "Control.Monad.Component.Internal.Types" "teardown-0.3.0.0-LZiK4LTLuZAIXZzqo3R66V" False) ((:+:) (C1 (MetaCons "ComponentFailure" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 Text))) (C1 (MetaCons "ComponentStartupFailure" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 [SomeException]))))

Teardown functions

data Teardown

Sub-routine that performs a resource cleanup operation

Instances

Generic Teardown

Associated Types

type Rep Teardown :: * -> *

Methods

from :: Teardown -> Rep Teardown x

to :: Rep Teardown x -> Teardown

NFData Teardown

Methods

rnf :: Teardown -> ()

type Rep Teardown

type Rep Teardown = D1 (MetaData "Teardown" "Control.Teardown.Internal.Types" "teardown-0.3.0.0-LZiK4LTLuZAIXZzqo3R66V" True) (C1 (MetaCons "Teardown" PrefixI False) (S1 (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (IO TeardownResult))))

data TeardownResult

Result from a Teardown sub-routine

Constructors

BranchResult

Result is composed by multiple teardown sub-routines

Fields

• resultDescription :: !Description

  Text description of parent teardown spec

• resultElapsedTime :: !NominalDiffTime

  Sum of elapsed time on sub-routines execution

• resultDidFail :: !Bool

  Tells if any sub-routines failed

• resultListing :: ![TeardownResult]

  Results of inner sub-routines

LeafResult

Result represents a single teardown sub-routine

Fields

• resultDescription :: !Description

  Text description of parent teardown spec

• resultElapsedTime :: !NominalDiffTime

  Sum of elapsed time on sub-routines execution

• resultError :: !(Maybe SomeException)

  Exception from sub-routine

EmptyResult

Represents a stub cleanup operation (for lifting pure values)

Fields

• resultDescription :: !Description

  Text description of parent teardown spec

Instances

Show TeardownResult

Methods

showsPrec :: Int -> TeardownResult -> ShowS

show :: TeardownResult -> String

showList :: [TeardownResult] -> ShowS

Generic TeardownResult

Associated Types

type Rep TeardownResult :: * -> *

Methods

from :: TeardownResult -> Rep TeardownResult x

to :: Rep TeardownResult x -> TeardownResult

NFData TeardownResult

Methods

rnf :: TeardownResult -> ()

type Rep TeardownResult

type Rep TeardownResult

teardown :: ITeardown teardown => teardown -> IO TeardownResult

Executes teardown sub-routine returning a TeardownResult

newTeardown :: IResource resource => Text -> resource -> IO Teardown

Re-exports

throwM :: MonadThrow m => forall e a. Exception e => e -> m a

Throw an exception. Note that this throws when this action is run in the monad m, not when it is applied. It is a generalization of Control.Exception's throwIO.

Should satisfy the law:

throwM e >> f = throwM e

fail :: MonadFail m => forall a. String -> m a

Functions to build ComponentM sub-routines

buildComponent :: IO a -> ComponentM a

Transforms an IO sub-routine into a ComponentM sub-routine; the given IO sub-routine returns a resource that does not allocate any other resources that would need to be cleaned up on a system shutdown.

buildComponentWithCleanup :: IO (a, (Text, IO ())) -> ComponentM a

Transforms an IO sub-routine into a ComponentM sub-routine; the given IO sub-routine must return a tuple where:

• First position represents the resource being returned from the component
• Second position represents a named cleanup action that tears down allocated resources to create the first element of the tuple

buildComponentWithTeardown :: IO (a, Teardown) -> ComponentM a

Transforms an IO sub-routine into a ComponentM sub-routine; the given IO sub-routine must return a tuple where:

• First position represents the resource being returned from the component
• Second position represents a Teardown record that cleans up allocated resources to create the first element of the tuple