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


-- | Build safe and composable teardown sub-routines for resources
--   
--   The teardown library allows you to reliably execute cleanup
--   sub-routines for allocated resources. When a program is initialized,
--   it:
--   
--   <ul>
--   <li>Ensures that teardown sub-routines are executed <i>exactly</i>
--   once</li>
--   <li>Ensures that if errors occur on the execution of a Teardown
--   sub-routine, the error does not propagate to others; bulkheading
--   failure on cleanup.</li>
--   <li>Requires every sub-routine to be documented at creation time; thus
--   helping tracing your application structure.</li>
--   <li>Allows tracing the teardown of your application, how is
--   structured, how much time it takes to execute, and what component (if
--   any) failed to finalize.</li>
--   </ul>
@package teardown
@version 0.5.0.0


-- | Provides functions that help on the creation of Application teardown
--   sub-routines
module Control.Teardown

-- | A record that <b>is</b> or <b>contains</b> a <a>Teardown</a>
--   sub-routine should instantiate this typeclass
class HasTeardown teardown

-- | Executes teardown sub-routine returning a <a>TeardownResult</a>
getTeardown :: HasTeardown teardown => teardown -> Teardown

-- | A resource or sub-routine that can be transformed into a
--   <a>Teardown</a> operation
class IResource resource

-- | Sub-routine that performs a resource cleanup operation
data Teardown

-- | Result from a <a>Teardown</a> sub-routine
data TeardownResult

-- | Result is composed by multiple teardown sub-routines
BranchResult :: !Description -> !NominalDiffTime -> !Bool -> ![TeardownResult] -> TeardownResult

-- | Text description of parent teardown spec
[resultDescription] :: TeardownResult -> !Description

-- | Sum of elapsed time on sub-routines execution
[resultElapsedTime] :: TeardownResult -> !NominalDiffTime

-- | Tells if any sub-routines failed
[resultDidFail] :: TeardownResult -> !Bool

-- | Results of inner sub-routines
[resultListing] :: TeardownResult -> ![TeardownResult]

-- | Result represents a single teardown sub-routine
LeafResult :: !Description -> !NominalDiffTime -> !(Maybe SomeException) -> TeardownResult

-- | Text description of parent teardown spec
[resultDescription] :: TeardownResult -> !Description

-- | Sum of elapsed time on sub-routines execution
[resultElapsedTime] :: TeardownResult -> !NominalDiffTime

-- | Exception from sub-routine
[resultError] :: TeardownResult -> !(Maybe SomeException)

-- | Represents a stub cleanup operation (for lifting pure values)
EmptyResult :: !Description -> TeardownResult

-- | Text description of parent teardown spec
[resultDescription] :: TeardownResult -> !Description

-- | Executes all composed <a>Teardown</a> sub-routines safely. This
--   version returns a Tree data structure wich can be used to gather facts
--   from the resource cleanup
runTeardown :: HasTeardown t => t -> IO TeardownResult

-- | Executes all composed <a>Teardown</a> sub-routines safely
runTeardown_ :: HasTeardown t => t -> IO ()

-- | Creates a stub <a>Teardown</a> sub-routine, normally used when a
--   contract expects a teardown return but there is no allocation being
--   made
emptyTeardown :: Description -> Teardown
newTeardown :: IResource resource => Text -> resource -> IO Teardown

-- | Returns a boolean indicating if any of the cleanup sub-routine failed
didTeardownFail :: TeardownResult -> Bool

-- | Returns number of sub-routines that threw an exception on execution of
--   "runTeardown"
failedToredownCount :: TeardownResult -> Int

-- | Returns number of released resources from a "runTeardown" execution
toredownCount :: TeardownResult -> Int

-- | Renders an ASCII Tree with the <a>TeardownResult</a> of a
--   <a>Teardown</a> sub-routine execution
prettyTeardownResult :: TeardownResult -> Doc ann
