Control.Concurrent.STM.Stats

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.

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

trackSTM :: STM a -> IO a

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

tryThreshold :: Maybe Int

If the number of retries of one transaction run reaches this count, a warning is issued at runtime. If set to Nothing, disables the warnings completely.

globalTheshold :: Maybe Int

If the total number of retries of one named transaction reaches this count, a warning is issued. If set to Nothing, disables the warnings completely.

extendException :: Bool

If this is set, a BlockedIndefinitelyOnSTM exception is replaced by a BlockedIndefinitelyOnNamedSTM exception, carrying the name of the exception.

warnFunction :: String -> IO ()

Function to call when a warning is to be emitted.

defaultTrackSTMConf :: TrackSTMConf

The default settings are:

 defaultTrackSTMConf = TrackSTMConf
    { tryThreshold =   Just 10
    , globalTheshold = Just 3000
    , exception =      True
    , warnFunction =   hPutStrLn stderr
    }

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

Instances

Show BlockedIndefinitelyOnNamedSTM

Typeable BlockedIndefinitelyOnNamedSTM

Exception BlockedIndefinitelyOnNamedSTM

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.