| Copyright | (c) 2011 David Leuschner (c) 2011 Joachim Breitner |
|---|---|
| License | BSD3 |
| Maintainer | Joachim Breitner <mail@joachim-breitner.de> |
| Portability | non-portable (requires STM) |
| Safe Haskell | None |
| Language | Haskell98 |
Control.Concurrent.STM.Stats
Contents
Description
This module provides variants to the function atomically from
Control.Concurrent.STM which keep track of how often the transaction is
initiated and how often it was retried.
- trackSTM :: STM a -> IO a
- trackNamedSTM :: String -> STM a -> IO a
- trackThisSTM :: Q Exp
- trackSTMConf :: TrackSTMConf -> String -> STM a -> IO a
- data TrackSTMConf = TrackSTMConf {
- tryThreshold :: Maybe Int
- globalTheshold :: Maybe Int
- extendException :: Bool
- warnFunction :: String -> IO ()
- warnInSTMFunction :: String -> IO ()
- defaultTrackSTMConf :: TrackSTMConf
- data BlockedIndefinitelyOnNamedSTM = BlockedIndefinitelyOnNamedSTM String
- getSTMStats :: IO (Map String (Int, Int))
- dumpSTMStats :: IO ()
Example usage
The following example code shows how to use the module:
import Control.Concurrent
import Control.Concurrent.STM
import Control.Monad
import Control.Concurrent.STM.Stats
main = do
var <- trackSTM $ newTVar 0
forkIO $ forM_ [1..23] $ i -> do
threadDelay (100*1000)
trackNamedSTM "writer" $ writeTVar var i
putStrLn "Starting reader..."
trackNamedSTM "reader" $ do
i <- readTVar var
when (i < 23) retry
putStrLn "Reader finished."
dumpSTMStats
Running this program will result in this output:
Starting reader... STM transaction reader finished after 23 retries Reader finished. STM transaction statistics (2011-10-09 12:28:37.188951 UTC): Transaction Commits Retries Ratio _anonymous_ 1 0 0.00 reader 1 23 23.00 writer 23 0 0.00
The function trackSTM is a direct replacement for atomically, while
trackNamedSTM and trackSTMConf provide more control and $trackThisSTM
uses Template Haskell to automatically generate a good name.
Generating statistics
A drop-in replacement for atomically. The statistics will list this, and
all other unnamed transactions, as "_anonymous_" and
BlockedIndefinitelyOnSTM exceptions will not be replaced.
See below for variants that give more control over the statistics and
generated warnings.
trackNamedSTM :: String -> STM a -> IO a #
Run atomically and collect the retry statistics under the given name and using the default configuration, defaultTrackSTMConf.
trackThisSTM :: Q Exp #
This, when used as $trackThisSTM in a module with -XTemplateHaskell enabled,
will call trackNamedSTM with a name automatically derived from the source
file name and position, e.g. "Test.hs:6:21".
trackSTMConf :: TrackSTMConf -> String -> STM a -> IO a #
Run atomically and collect the retry statistics under the given name,
while issuing warnings when the configured thresholds are exceeded.
Configuring TrackSTM
data TrackSTMConf #
For the most general transaction tracking function, trackSTMConf, all
settings can be configured using a TrackSTMConf value.
Constructors
| TrackSTMConf | |
Fields
| |
defaultTrackSTMConf :: TrackSTMConf #
The default settings are:
defaultTrackSTMConf = TrackSTMConf
{ tryThreshold = Just 10
, globalTheshold = Just 3000
, exception = True
, warnFunction = hPutStrLn stderr
, warnInSTMFunction = \_ -> return ()
}More helpful exceptions
data BlockedIndefinitelyOnNamedSTM #
If extendException is set (which is the case with trackNamedSTM), an
occurrence of BlockedIndefinitelyOnSTM is replaced by
BlockedIndefinitelyOnNamedSTM, carrying the name of the transaction and
thus giving more helpful error messages.
Constructors
| BlockedIndefinitelyOnNamedSTM String |
Reading the statistics
getSTMStats :: IO (Map String (Int, Int)) #
Fetches the current transaction statistics data.
The map maps transaction names to counts of transaction commits and transaction retries.
dumpSTMStats :: IO () #
Dumps the current transaction statistics data to stderr.