teardown 0.0.0.1 → 0.0.0.2

raw patch · 5 files changed

+88/−13 lines, 5 filesPVP: minor bump suggested

API additions: PVP suggests at least a minor version bump

API changes (from Hackage documentation)

Files

• CHANGELOG.md +4/−0
• src/Control/Teardown.hs +41/−8
• src/Control/Teardown/Internal/Core.hs +40/−4
• src/Control/Teardown/Internal/Printer.hs +2/−0
• teardown.cabal +1/−1

@@ -7,6 +7,10 @@ [1]: http://semver.org/spec/v2.0.0.html [2]: https://github.com/roman/Haskell-teardown/libraries/teardown/CHANGELOG.md +## v0.0.0.2++* Add haddock documentation to modules+ ## v0.0.0.1  * First release of teardown library

@@ -1,17 +1,50 @@ {-# LANGUAGE NoImplicitPrelude #-} {-# LANGUAGE OverloadedStrings #-}-module Control.Teardown ( module X ) where+{-|+Module      : Control.Teardown+Description : Build composable, idempotent & transparent application cleanup sub-routines+Copyright   : (c) Roman Gonzalez, 2017+License     : MIT+Maintainer  : romanandreg@gmail.com+Stability   : experimental -import Control.Teardown.Internal.Core    as X-    ( ITeardown (..)+Provides functions that help on the creation of Application teardown+sub-routines+-}+module Control.Teardown+  ( ITeardown+  -- * Cleanup main type and function+  , Teardown+  , teardown++  -- * Functions to create a 'Teardown' record+  , emptyTeardown+  , newTeardown+  , newDynTeardown+  , concatTeardown++  -- * Functions to deal with results from 'teardown' call+  , TeardownResult (..)+  , didTeardownFail+  , failedToredownCount+  , toredownCount+  , renderTeardownReport+  ) where++import Control.Teardown.Internal.Core+    ( ITeardown     , Teardown-    , TeardownResult (..)+    , teardown++    , emptyTeardown+    , newTeardown+    , newDynTeardown     , concatTeardown++    , TeardownResult (..)     , didTeardownFail-    , emptyTeardown     , failedToredownCount-    , newDynTeardown-    , newTeardown     , toredownCount     )-import Control.Teardown.Internal.Printer as X (renderTeardownReport)++import Control.Teardown.Internal.Printer (renderTeardownReport)

@@ -13,31 +13,47 @@  type Description = Text +-- | Result from a 'Teardown' sub-routine data TeardownResult+  -- | Result is composed by multiple teardown sub-routines   = BranchResult     {+      -- | Text description of parent teardown spec       resultDescription :: !Description+      -- | Sum of elapsed time on sub-routines execution     , resultElapsedTime :: !NominalDiffTime+      -- | Tells if any sub-routines failed     , resultDidFail     :: !Bool+      -- | Results of inner sub-routines     , resultListing     :: ![TeardownResult]     }+  -- | Result represents a single teardown sub-routine   | LeafResult     {+      -- | Text description of sub-routine       resultDescription :: !Description+      -- | Elapsed time on sub-routine execution     , resultElapsedTime :: !NominalDiffTime+      -- | Exception from sub-routine     , resultError       :: !(Maybe SomeException)     }+  -- | Represents a stub cleanup operation (for lifting pure values)   | EmptyResult     {+      -- | Text description of faked sub-routine       resultDescription :: !Description     }   deriving (Generic, Show) +-- | Sub-routine that performs a resource cleanup operation newtype Teardown   = Teardown (IO TeardownResult)   deriving (Generic) +-- | A record that __is__ or __contains__ a 'Teardown' sub-routine should+-- instantiate this typeclass class ITeardown d where+  -- | Executes teardown sub-routine returning a "TeardownResult"   teardown :: d -> IO TeardownResult  --------------------------------------------------------------------------------@@ -52,6 +68,7 @@ emptyTeardownResult :: Description -> TeardownResult emptyTeardownResult = EmptyResult +-- | Returns a boolean indicating if any of the cleanup sub-routine failed didTeardownFail :: TeardownResult -> Bool didTeardownFail result =   case result of@@ -64,6 +81,10 @@     EmptyResult {} ->       False +-- | Creates a new "Teardown" sub-routine from a cleanup "IO" action, the+-- side-effects from this action are guaranteed to be executed only once, and+-- also it is guaranteed to be thread-safe in the scenario of multiple threads+-- executing the same teardown procedure. newTeardown :: Description -> IO () -> IO Teardown newTeardown desc disposingAction = do   teardownResultLock <- newIORef False@@ -88,6 +109,9 @@       else           fromMaybe (emptyTeardownResult desc) <$> readIORef teardownResultRef +-- | Creates a "Teardown" sub-routine that is composed of other smaller sub-routines. This+-- is ideal for composing the cleanup of an application from smaller resources allocations that+-- are known at compilation time. concatTeardown :: Description -> [Teardown] -> Teardown concatTeardown desc teardownChildren = Teardown $ do   teardownResults <- mapM (\(Teardown action) -> action) teardownChildren@@ -101,6 +125,11 @@    return $ BranchResult desc elapsed teardownFailed teardownResults +-- | Creates a "Teardown" sub-routine that is composed of inner sub-routines+--  that are allocated at runtime. This is useful if allocations are being+--  created and being hold on a Mutable variable of some sort (e.g. "IORef",+--  "TVar", etc) so that on cleanup this Mutable variable is read and the+--  results of the teardown operation are returned. newDynTeardown :: Description -> IO [TeardownResult] -> Teardown newDynTeardown desc action = Teardown $ do   teardownResults <- action@@ -114,17 +143,21 @@    return $ BranchResult desc elapsed teardownFailed teardownResults +-- | Creates a stub "Teardown" sub-routine, normally used when a contract+--  expects a teardown return but there is no allocation being made emptyTeardown :: Description -> Teardown emptyTeardown desc =   Teardown (return $ emptyTeardownResult desc)  -------------------------------------------------------------------------------- +-- | Aggregate the results of a "Teardown" sub-routine, having a function+--   for parent and leaf sub-routines from the teardown tree. foldTeardownResult-  :: (acc -> Description -> Maybe SomeException -> acc)-  -> ([acc] -> Description -> acc)-  -> acc-  -> TeardownResult+  :: (acc -> Description -> Maybe SomeException -> acc) -- ^ Step function called when the "TeardownResult" is a leaf+  -> ([acc] -> Description -> acc) -- ^ Step function called when the "TeardownResult" is a branch+  -> acc -- ^ Original fold accumulator+  -> TeardownResult -- ^ Result from the "teardown" execution   -> acc foldTeardownResult leafStep branchStep acc disposeResult =   case disposeResult of@@ -141,12 +174,15 @@       in         branchStep result desc +-- | Returns number of sub-routines executed at teardown toredownCount :: TeardownResult -> Int toredownCount =   foldTeardownResult (\acc _ _ -> acc + 1)                      (\results _ -> sum results)                      0 +-- | Returns number of sub-routines that threw an exception on execution of+-- teardown failedToredownCount :: TeardownResult -> Int failedToredownCount =   foldTeardownResult (\acc _ mErr -> acc + maybe 0 (const 1) mErr)

@@ -16,6 +16,8 @@   hcat (map (\_ -> text "    ") [1..start]) <>   hcat (map (\_ -> text "   |") [start..pred level]) +-- | Renders an ASCII Tree with the "TeardownResult" of a "Teardown" sub-routine+-- execution renderTeardownReport :: TeardownResult -> Doc renderTeardownReport result =     render 0 0 result <> hardline

@@ -3,7 +3,7 @@ -- see: https://github.com/sol/hpack  name:           teardown-version:        0.0.0.1+version:        0.0.0.2 synopsis:       Build composable, idempotent & transparent application cleanup sub-routines description:    Please see README.md category:       System