-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | low-level performance statistics
--
-- A set of tools to measure time performance.
@package perf
@version 0.2.0
-- | tick uses the rdtsc chipset to measure time performance of a
-- computation.
--
-- The measurement unit - a Cycle - is one oscillation of the chip
-- crystal as measured by the rdtsc instruction which inspects the
-- TSC register.
--
-- For reference, a computer with a frequency of 2 GHz means that one
-- cycle is equivalent to 0.5 nanoseconds.
module Perf.Cycle
-- | an unwrapped Word64
type Cycle = Word64
-- | tick_ measures the number of cycles it takes to read the rdtsc chip
-- twice: the difference is then how long it took to read the clock the
-- second time.
--
-- Below are indicative measurements using tick_:
--
--
-- >>> onetick <- tick_
--
-- >>> ticks' <- replicateM 10 tick_
--
-- >>> manyticks <- replicateM 1000000 tick_
--
-- >>> let average = L.fold ((/) <$> L.sum <*> L.genericLength)
--
-- >>> let avticks = average (fromIntegral <$> manyticks)
--
-- >>> let qticks = deciles 10 manyticks
--
-- >>> let tick999 = percentile 0.999 manyticks
--
--
--
-- one tick_: 78 cycles
-- next 10: [20,18,20,20,20,20,18,16,20,20]
-- average over 1m: 20.08 cycles
-- 99.999% perc: 7,986
-- 99.9% perc: 50.97
-- 99th perc: 24.99
-- 40th perc: 18.37
-- [min, 10th, 20th, .. 90th, max]:
-- 12.00 16.60 17.39 17.88 18.37 18.86 19.46 20.11 20.75 23.04 5.447e5
--
--
-- The distribution of tick_ measurements is highly skewed, with the
-- maximum being around 50k cycles, which is of the order of a GC. The
-- important point on the distribution is around the 30th to 50th
-- percentile, where you get a clean measure, usually free of GC activity
-- and cache miss-fires
tick_ :: IO Cycle
-- | Warm up the register, to avoid a high first measurement. Without a
-- warmup, one or more larger values can occur at the start of a
-- measurement spree, and often are in the zone of an L2 miss.
--
--
-- >>> t <- tick_ -- first measure can be very high
--
-- >>> _ <- warmup 100
--
-- >>> t <- tick_ -- should be around 20 (3k for ghci)
--
warmup :: Int -> IO Double
-- | `tick f a` strictly applies a to f, and returns a (Cycle, f a)
--
--
-- >>> _ <- warmup 100
--
-- >>> (cs, _) <- tick f a
--
--
--
-- one tick: 197012 cycles
-- average over 1000: 10222.79 cycles -- 10 cycles per operation
-- [min, 30th, median, 90th, 99th, max]:
-- 1.002e4 1.011e4 1.013e4 1.044e4 1.051e4 2.623e4
--
tick :: (a -> b) -> a -> IO (Cycle, b)
-- | needs more testing
app :: t -> () -> t
-- | evaluates and measures an `IO a`
--
--
-- >>> (cs, _) <- tickIO (pure (f a))
--
tickIO :: IO a -> IO (Cycle, a)
-- | n measurements of a tick
--
-- returns a list of Cycles and the last evaluated f a
--
-- GHC is very good as memoization, and any of the functions that
-- measuring a computation multiple times are fraught. When a computation
-- actually gets memoized is an inexact science. Current readings are:
--
--
-- sum to 1000.0
-- Perf.ticks n f a 8.37e3 cycles
-- Main.ticks n f a 8.38e3 cycles
-- Perf.ticksIO n (pure $ f a) 8.38e3 cycles
-- Perf.qtick n f a 8.38e3 cycles
-- Main.qtick n f a 8.38e3 cycles
-- replicateM n (tick f a) 8.37e3 cycles
-- replicateM' n (tick f a) 9.74e3 cycles
-- replicateM n (tickIO (pure (f a))) 1.21e4 cycles
-- replicateM n (tick (app (f a)) ()) 9.72e3 cycles
-- replicateM n (tick identity (f n)) 18.2 cycles
-- replicateM n (tick (const (f a)) ()) 9.71e3 cycles
-- (replicateM n . tick f) <$> [1,10,100,1000,10000]: 16.3 16.2 16.3 16.2 16.2
-- Perf.tickns n f [1,10,100,1000,10000]: 16.2 16.2 16.2 16.2 16.2
--
--
--
-- >>> let n = 1000
--
-- >>> (cs, fa) <- ticks n f a
--
ticks :: Int -> (a -> b) -> a -> IO ([Cycle], b)
-- | returns the 40th percentile measurement and the last evaluated f a
--
--
-- >>> (c, fa) <- qtick n f a
--
qtick :: Int -> (a -> b) -> a -> IO (Double, b)
-- | n measuremenst of a tickIO
--
-- returns an IO tuple; list of Cycles and the last evaluated f a
--
--
-- >>> (cs, fa) <- ticksIO n (pure $ f a)
--
ticksIO :: Int -> IO a -> IO ([Cycle], a)
-- | n measurements on each of a list of a's to be applied to f.
--
-- Currently memoizing it's ass off
--
--
-- tickns n f [1,10,100,1000]
--
tickns :: Int -> (a -> b) -> [a] -> IO ([[Cycle]], [b])
-- | extra oomph for those hard to reach evaluations
force :: (NFData a) => a -> a
-- | a replicateM with good attributes
replicateM' :: Monad m => Int -> m a -> m [a]
-- | average of a Cycle foldable
--
--
-- cAv <- average <$> ticks n f a
--
average :: (Foldable f) => f Cycle -> Double
-- | compute deciles
--
--
-- c5 <- decile 5 <$> ticks n f a
--
deciles :: (Functor f, Foldable f) => Int -> f Cycle -> [Double]
-- | compute a percentile
--
--
-- c <- percentoile 0.4 <$> ticks n f a
--
percentile :: (Functor f, Foldable f) => Double -> f Cycle -> Double
instance NumHask.Algebra.Additive.AdditiveMagma Perf.Cycle.Cycle
instance NumHask.Algebra.Additive.AdditiveUnital Perf.Cycle.Cycle
instance NumHask.Algebra.Additive.AdditiveAssociative Perf.Cycle.Cycle
instance NumHask.Algebra.Additive.AdditiveCommutative Perf.Cycle.Cycle
instance NumHask.Algebra.Additive.Additive Perf.Cycle.Cycle
instance NumHask.Algebra.Additive.AdditiveInvertible Perf.Cycle.Cycle
instance NumHask.Algebra.Additive.AdditiveGroup Perf.Cycle.Cycle
instance NumHask.Algebra.Integral.ToInteger Perf.Cycle.Cycle
-- | Specification of a performance measurement type suitable for the
-- PerfT monad transformer.
module Perf.Measure
-- | A Measure consists of a monadic effect prior to measuring, a monadic
-- effect to finalise the measurement, and the value measured
--
-- For example, the measure specified below will return 1 every time
-- measurement is requested, thus forming the base of a simple counter
-- for loopy code.
--
--
-- >>> let count = Measure 0 (pure ()) (pure 1)
--
data Measure m b
Measure :: b -> m a -> (a -> m b) -> Measure m b
[measure] :: Measure m b -> b
[prestep] :: Measure m b -> m a
[poststep] :: Measure m b -> a -> m b
-- | Measure a single effect.
--
--
-- >>> r <- runMeasure count (pure "joy")
--
-- >>> r
-- (1,"joy")
--
runMeasure :: (MonadIO m) => Measure m b -> m a -> m (b, a)
-- | Measure once, but run an effect multiple times.
--
--
-- >>> r <- runMeasureN 1000 count (pure "joys")
--
-- >>> r
-- (1,"joys")
--
runMeasureN :: (MonadIO m) => Int -> Measure m b -> m a -> m (b, a)
-- | cost of a measurement in terms of the Measure's own units
--
--
-- >>> r <- cost count
--
-- >>> r
-- 1
--
cost :: (MonadIO m) => Measure m b -> m b
-- | a measure using getCPUTime from System.CPUTime (unit is
-- picoseconds)
--
--
-- >>> r <- runMeasure cputime (pure $ foldl' (+) 0 [0..1000])
--
--
--
-- (34000000,500500)
--
cputime :: Measure IO Integer
-- | a measure using getCurrentTime (unit is NominalDiffTime
-- which prints as seconds)
--
--
-- >>> r <- runMeasure realtime (pure $ foldl' (+) 0 [0..1000])
--
--
--
-- (0.000046s,500500)
--
realtime :: Measure IO NominalDiffTime
-- | a measure used to count iterations
--
--
-- >>> r <- runMeasure count (pure ())
--
-- >>> r
-- (1,())
--
count :: Measure IO Int
-- | a Measure using the rdtsc chip set (units are in cycles)
--
--
-- >>> r <- runMeasureN 1000 cycles (pure ())
--
--
--
-- (120540,()) -- ghci-level
-- (18673,()) -- compiled with -O2
--
cycles :: Measure IO Cycle
instance NumHask.Algebra.Additive.AdditiveMagma Data.Time.Clock.UTC.NominalDiffTime
instance NumHask.Algebra.Additive.AdditiveUnital Data.Time.Clock.UTC.NominalDiffTime
instance NumHask.Algebra.Additive.AdditiveAssociative Data.Time.Clock.UTC.NominalDiffTime
instance NumHask.Algebra.Additive.AdditiveCommutative Data.Time.Clock.UTC.NominalDiffTime
instance NumHask.Algebra.Additive.Additive Data.Time.Clock.UTC.NominalDiffTime
instance NumHask.Algebra.Additive.AdditiveInvertible Data.Time.Clock.UTC.NominalDiffTime
instance NumHask.Algebra.Additive.AdditiveGroup Data.Time.Clock.UTC.NominalDiffTime
-- | PerfT is a monad transformer designed to collect performance
-- information. The transformer can be used to add performance measurent
-- to an existing code base using Measures.
--
-- For example, here's some code doing some cheesey stuff:
--
--
-- -- prior to Perfification
-- result <- do
-- txt <- readFile "examples/examples.hs"
-- let n = Text.length txt
-- let x = foldl' (+) 0 [1..n]
-- putStrLn $ "sum of one to number of characters is: " <>
-- (show x :: Text)
-- pure (n, x)
--
--
-- And here's the code after Perfification, measuring performance
-- of the components.
--
--
-- (result', ms) <- runPerfT $ do
-- txt <- perf "file read" cycles $ readFile "examples/examples.hs"
-- n <- perf "length" cycles $ pure (Text.length txt)
-- x <- perf "sum" cycles $ pure (foldl' (+) 0 [1..n])
-- perf "print to screen" cycles $
-- putStrLn $ "sum of one to number of characters is: " <>
-- (show x :: Text)
-- pure (n, x)
--
--
-- Running the code produces a tuple of the original computation results,
-- and a Map of performance measurements that were specified. Indicative
-- results:
--
--
-- file read 4.92e5 cycles
-- length 1.60e6 cycles
-- print to screen 1.06e5 cycles
-- sum 8.12e3 cycles
--
module Perf
-- | PerfT is polymorphic in the type of measurement being performed. The
-- monad stores and produces a Map of labelled measurement values
data PerfT m b a
-- | The obligatory transformer over Identity
type Perf b a = PerfT Identity b a
-- | Lift a monadic computation to a PerfT m, providing a label and a
-- Measure.
perf :: (MonadIO m, Additive b) => Text -> Measure m b -> m a -> PerfT m b a
-- | Lift a monadic computation to a PerfT m, and carry out the computation
-- multiple times.
perfN :: (MonadIO m, Semigroup b, Monoid b) => Int -> Text -> Measure m b -> m a -> PerfT m b a
-- | Consume the PerfT layer and return a (result, measurement).
--
--
-- >>> :set -XOverloadedStrings
--
-- >>> (cs, result) <- runPerfT $ perf "sum" cycles (pure $ foldl' (+) 0 [0..10000])
--
--
--
-- (50005000,fromList [("sum",562028)])
--
runPerfT :: PerfT m b a -> m (a, Map Text b)
-- | Consume the PerfT layer and return the original monadic result.
-- Fingers crossed, PerfT structure should be completely compiled away.
--
--
-- >>> result <- evalPerfT $ perf "sum" cycles (pure $ foldl' (+) 0 [0..10000])
--
--
--
-- 50005000
--
evalPerfT :: (Monad m) => PerfT m b a -> m a
-- | Consume a PerfT layer and return the measurement.
--
--
-- >>> cs <- execPerfT $ perf "sum" cycles (pure $ foldl' (+) 0 [0..10000])
--
--
--
-- fromList [("sum",562028)]
--
execPerfT :: (Monad m) => PerfT m b a -> m (Map Text b)
instance GHC.Base.Monad m => GHC.Base.Monad (Perf.PerfT m b)
instance GHC.Base.Monad m => GHC.Base.Applicative (Perf.PerfT m b)
instance GHC.Base.Functor m => GHC.Base.Functor (Perf.PerfT m b)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Perf.PerfT m b)