| Copyright | (c) Roman Gonzalez 2017 |
|---|---|
| License | MIT |
| Maintainer | romanandreg@gmail.com |
| Stability | experimental |
| Safe Haskell | Safe |
| Language | Haskell2010 |
Control.Monad.Component
Contents
Description
Provides functions that help on the creation of Application teardown sub-routines
- data ComponentM a
- runComponentM :: Text -> ComponentM a -> IO (Component a)
- data Component a
- fromComponent :: Component a -> a
- data ComponentError
- data Teardown
- data TeardownResult
- = BranchResult {
- resultDescription :: !Description
- resultElapsedTime :: !NominalDiffTime
- resultDidFail :: !Bool
- resultListing :: ![TeardownResult]
- | LeafResult {
- resultDescription :: !Description
- resultElapsedTime :: !NominalDiffTime
- resultError :: !(Maybe SomeException)
- | EmptyResult {
- resultDescription :: !Description
- = BranchResult {
- teardown :: ITeardown teardown => teardown -> IO TeardownResult
- newTeardown :: IResource resource => Text -> resource -> IO Teardown
- throwM :: MonadThrow m => forall e a. Exception e => e -> m a
- fail :: MonadFail m => forall a. String -> m a
- buildComponent :: IO a -> ComponentM a
- buildComponentWithCleanup :: IO (a, (Text, IO ())) -> ComponentM a
- buildComponentWithTeardown :: IO (a, Teardown) -> ComponentM a
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.
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
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.
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
Teardown functions
Sub-routine that performs a resource cleanup operation
data TeardownResult #
Result from a Teardown sub-routine
Constructors
| BranchResult | Result is composed by multiple teardown sub-routines |
Fields
| |
| LeafResult | Result represents a single teardown sub-routine |
Fields
| |
| EmptyResult | Represents a stub cleanup operation (for lifting pure values) |
Fields
| |
Instances
teardown :: ITeardown teardown => teardown -> IO TeardownResult #
Executes teardown sub-routine returning a TeardownResult
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
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
Teardownrecord that cleans up allocated resources to create the first element of the tuple