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


-- | retry statistics for STM transactions
--   
--   This module provides functions that can replace calls to
--   <a>atomically</a> and count how often the transaction was retried
--   until it succeeded. It can emit warnings when transaction are retried
--   more often than a given threshold, and provides global statistics
--   across all transaction.
--   
--   As an additional feature, if the transaction was named,
--   transaction-related exceptions such as <a>BlockedIndefinitelyOnSTM</a>
--   are replaced by variants that indicate which transaction caused the
--   exception.
--   
--   <i>Changelog:</i>
--   
--   <a>0.2.0.0</a>
--   
--   <ul>
--   <li><i> </i> Added <a>warnInSTMFunction</a> to
--   <a>TrackSTMConf</a>.</li>
--   <li><i> </i> Bugfix with the global retry count warning.</li>
--   <li><i>0.1.0.0</i> (2011-10-09)</li>
--   <li><i> </i> Initial Release</li>
--   </ul>
@package stm-stats
@version 0.2.0.0


-- | This module provides variants to the function <a>atomically</a> from
--   <a>Control.Concurrent.STM</a> which keep track of how often the
--   transaction is initiated and how often it was retried.
module Control.Concurrent.STM.Stats

-- | A drop-in replacement for <a>atomically</a>. The statistics will list
--   this, and all other unnamed transactions, as "<tt>_anonymous_</tt>"
--   and <a>BlockedIndefinitelyOnSTM</a> exceptions will not be replaced.
--   See below for variants that give more control over the statistics and
--   generated warnings.
trackSTM :: STM a -> IO a

-- | Run <a>atomically</a> and collect the retry statistics under the given
--   name and using the default configuration, <a>defaultTrackSTMConf</a>.
trackNamedSTM :: String -> STM a -> IO a

-- | This, when used as <tt>$trackThisSTM</tt> in a module with
--   <tt>-XTemplateHaskell</tt> enabled, will call <a>trackNamedSTM</a>
--   with a name automatically derived from the source file name and
--   position, e.g. "<tt>Test.hs:6:21</tt>".
trackThisSTM :: Q Exp

-- | Run <a>atomically</a> and collect the retry statistics under the given
--   name, while issuing warnings when the configured thresholds are
--   exceeded.
trackSTMConf :: TrackSTMConf -> String -> STM a -> IO a

-- | For the most general transaction tracking function,
--   <a>trackSTMConf</a>, all settings can be configured using a
--   <a>TrackSTMConf</a> value.
data TrackSTMConf
TrackSTMConf :: Maybe Int -> Maybe Int -> Bool -> String -> IO () -> String -> IO () -> TrackSTMConf

-- | If the number of retries of one transaction run reaches this count, a
--   warning is issued at runtime. If set to <tt>Nothing</tt>, disables the
--   warnings completely.
[tryThreshold] :: TrackSTMConf -> Maybe Int

-- | If the total number of retries of one named transaction reaches this
--   count, a warning is issued. If set to <tt>Nothing</tt>, disables the
--   warnings completely.
[globalTheshold] :: TrackSTMConf -> Maybe Int

-- | If this is set, a <a>BlockedIndefinitelyOnSTM</a> exception is
--   replaced by a <a>BlockedIndefinitelyOnNamedSTM</a> exception, carrying
--   the name of the exception.
[extendException] :: TrackSTMConf -> Bool

-- | Function to call when a warning is to be emitted.
[warnFunction] :: TrackSTMConf -> String -> IO ()

-- | Function to call when a warning is to be emitted during an STM
--   transaction. This is possibly dangerous, see the documentation to
--   <a>unsafeIOToSTM</a>, but can be useful to detect transactions that
--   keep retrying forever.
[warnInSTMFunction] :: TrackSTMConf -> String -> IO ()

-- | The default settings are:
--   
--   <pre>
--   defaultTrackSTMConf = TrackSTMConf
--      { tryThreshold =      Just 10
--      , globalTheshold =    Just 3000
--      , exception =         True
--      , warnFunction =      hPutStrLn stderr
--      , warnInSTMFunction = \_ -&gt; return ()
--      }
--   </pre>
defaultTrackSTMConf :: TrackSTMConf

-- | If <a>extendException</a> is set (which is the case with
--   <a>trackNamedSTM</a>), an occurrence of
--   <a>BlockedIndefinitelyOnSTM</a> is replaced by
--   <a>BlockedIndefinitelyOnNamedSTM</a>, carrying the name of the
--   transaction and thus giving more helpful error messages.
data BlockedIndefinitelyOnNamedSTM
BlockedIndefinitelyOnNamedSTM :: String -> BlockedIndefinitelyOnNamedSTM

-- | Fetches the current transaction statistics data.
--   
--   The map maps transaction names to counts of transaction commits and
--   transaction retries.
getSTMStats :: IO (Map String (Int, Int))

-- | Dumps the current transaction statistics data to <a>stderr</a>.
dumpSTMStats :: IO ()
instance GHC.Show.Show Control.Concurrent.STM.Stats.BlockedIndefinitelyOnNamedSTM
instance GHC.Exception.Exception Control.Concurrent.STM.Stats.BlockedIndefinitelyOnNamedSTM
