stm-stats-0.2.0.0: retry statistics for STM transactions

Copyright(c) 2011 David Leuschner
(c) 2011 Joachim Breitner
LicenseBSD3
MaintainerJoachim Breitner <mail@joachim-breitner.de>
Portabilitynon-portable (requires STM)
Safe HaskellNone
LanguageHaskell98

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.

Synopsis

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

defaultTrackSTMConf :: TrackSTMConf #

The default settings are:

defaultTrackSTMConf = TrackSTMConf
   { tryThreshold =      Just 10
   , globalTheshold =    Just 3000
   , exception =         True
   , warnFunction =      hPutStrLn stderr
   , warnInSTMFunction = \_ -> return ()
   }

More helpful exceptions

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.