Debug.TimeStats

A module to collect aggregates on how much time is spent in a computation

Aggregates can be identified with a label that determines where the time of each computation is accounted for.

Measures are collected only if the environment variable DEBUG_TIMESTATS_ENABLE is set to any value ahead of invoking any function in this module.

Measuring

measureM :: Monad m => String -> m a -> m a

Measure the time it takes to run the action.

Add the time to the stats of the given label and increase its count by one.

measureM keeps the stats in a globally available store in order to minimize the changes necessary when instrumenting a program. Otherwise a reference to the store would need to be passed to every function that might invoke functions that need this reference.

A time measure isn't collected if the given action fails with an exception. This is a deliberate choice to demand less of the monad in which measures are taken.

Time measures aren't collected either if the environment variable DEBUG_TIMESTATS_ENABLE isn't set the first time this function is evaluated.

measurePure :: String -> a -> a

Pure version of measureM. Measures the time taken to reduce the given value to head normal form.

measurePure is a bit dangerous to use in contexts where there are monadic computations. If measurePure is applied to a monadic computation it will measure the time of constructing the computation rather than the time of executing it, and the typechecker won't catch the mistake. We try to fence against it with a longer name.

Time stats manipulation

printTimeStats :: Monad m => m ()

Prints the time stats to stderr.

hPrintTimeStats :: Monad m => Handle -> m ()

Prints the time stats to the given handle.

reset :: Monad m => m ()

Set all statistics to initial values.

data TimeStats

Reports how much time (in nanoseconds) the invocations to measureM took for a given label and how many times it was invoked on a given label.

Constructors

TimeStats

Fields

• timeStat :: !Word64
• countStat :: !Int

Instances

Show TimeStats

Defined in Debug.TimeStats

Methods

showsPrec :: Int -> TimeStats -> ShowS

show :: TimeStats -> String

showList :: [TimeStats] -> ShowS

collect :: Monad m => m [(String, TimeStats)]

Yields the labels and the stats collected thus far.

asText :: [(String, TimeStats)] -> Text

Renders the given time stats in a tabular format

scope :: Monad m => m a -> m a

Run an action by previously reseting all stats to initial values and printing them afterwards.

Not intended for direct use

These definitions are not intended for instrumenting applications, but they can be handy to implement other measuring primitives.

data TimeStatsRef

A reference to a TimeStats value

lookupTimeStatsRef :: String -> IO TimeStatsRef

Looks up the stats of a label. If no stats are found for the label, a new TimeStatsRef is created with initial values.

updateTimeStatsRef :: TimeStatsRef -> (TimeStats -> TimeStats) -> IO ()

Updates the TimeStats in a TimeStatsRef