criterion-measurement-0.2.1.0: Criterion measurement functionality and associated types
Copyright(c) 2009-2014 Bryan O'Sullivan
LicenseBSD-style
Maintainerbos@serpentine.com
Stabilityexperimental
PortabilityGHC
Safe HaskellTrustworthy
LanguageHaskell2010

Criterion.Measurement

Description

Benchmark measurement code.

Synopsis

Documentation

initializeTime :: IO () Source #

Set up time measurement.

criterion measures time using OS-specific APIs whenever possible for efficiency. On certain operating systems, such as macOS and Windows, one must explicitly initialize a timer (which initializeTime accomplishes) before one can actually measure the current time (which getTime accomplishes).

It is imperative that you call initializeTime before calling getTime. (See this bug report for an example of what can happen if you do not do so.) All of the IO-returning functions in Criterion.Main make sure that this is done, but other functions (such as those in Criterion.Measurement) do not guarantee this unless otherwise stated.

getTime :: IO Double Source #

Return the current wallclock time, in seconds since some arbitrary time.

You must call initializeTime once before calling this function! Refer to the documentation for initializeTime for more details.

getCPUTime :: IO Double Source #

Return the amount of elapsed CPU time, combining user and kernel (system) time into a single measure.

getCycles :: IO Word64 Source #

Read the CPU cycle counter.

getGCStatistics :: IO (Maybe GCStatistics) Source #

Try to get GC statistics, bearing in mind that the GHC runtime will throw an exception if statistics collection was not enabled using "+RTS -T".

If you need guaranteed up-to-date stats, call performGC first.

data GCStatistics Source #

Statistics about memory usage and the garbage collector. Apart from gcStatsCurrentBytesUsed and gcStatsCurrentBytesSlop all are cumulative values since the program started.

GCStatistics is cargo-culted from the GCStats data type that GHC.Stats used to export. Since GCStats was removed in GHC 8.4, criterion uses GCStatistics to provide a backwards-compatible view of GC statistics.

Constructors

GCStatistics 

Fields

Instances

Instances details
Data GCStatistics Source # 
Instance details

Defined in Criterion.Measurement

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> GCStatistics -> c GCStatistics #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c GCStatistics #

toConstr :: GCStatistics -> Constr #

dataTypeOf :: GCStatistics -> DataType #

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c GCStatistics) #

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c GCStatistics) #

gmapT :: (forall b. Data b => b -> b) -> GCStatistics -> GCStatistics #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> GCStatistics -> r #

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> GCStatistics -> r #

gmapQ :: (forall d. Data d => d -> u) -> GCStatistics -> [u] #

gmapQi :: Int -> (forall d. Data d => d -> u) -> GCStatistics -> u #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> GCStatistics -> m GCStatistics #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> GCStatistics -> m GCStatistics #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> GCStatistics -> m GCStatistics #

Generic GCStatistics Source # 
Instance details

Defined in Criterion.Measurement

Associated Types

type Rep GCStatistics :: Type -> Type #

Read GCStatistics Source # 
Instance details

Defined in Criterion.Measurement

Show GCStatistics Source # 
Instance details

Defined in Criterion.Measurement

Eq GCStatistics Source # 
Instance details

Defined in Criterion.Measurement

type Rep GCStatistics Source # 
Instance details

Defined in Criterion.Measurement

type Rep GCStatistics = D1 ('MetaData "GCStatistics" "Criterion.Measurement" "criterion-measurement-0.2.1.0-IMsUsdPbXwrGQG7rGuCdpl" 'False) (C1 ('MetaCons "GCStatistics" 'PrefixI 'True) ((((S1 ('MetaSel ('Just "gcStatsBytesAllocated") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int64) :*: S1 ('MetaSel ('Just "gcStatsNumGcs") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int64)) :*: (S1 ('MetaSel ('Just "gcStatsMaxBytesUsed") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int64) :*: S1 ('MetaSel ('Just "gcStatsNumByteUsageSamples") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int64))) :*: ((S1 ('MetaSel ('Just "gcStatsCumulativeBytesUsed") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int64) :*: S1 ('MetaSel ('Just "gcStatsBytesCopied") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int64)) :*: (S1 ('MetaSel ('Just "gcStatsCurrentBytesUsed") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int64) :*: S1 ('MetaSel ('Just "gcStatsCurrentBytesSlop") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int64)))) :*: (((S1 ('MetaSel ('Just "gcStatsMaxBytesSlop") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int64) :*: S1 ('MetaSel ('Just "gcStatsPeakMegabytesAllocated") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int64)) :*: (S1 ('MetaSel ('Just "gcStatsMutatorCpuSeconds") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Double) :*: S1 ('MetaSel ('Just "gcStatsMutatorWallSeconds") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Double))) :*: ((S1 ('MetaSel ('Just "gcStatsGcCpuSeconds") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Double) :*: S1 ('MetaSel ('Just "gcStatsGcWallSeconds") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Double)) :*: (S1 ('MetaSel ('Just "gcStatsCpuSeconds") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Double) :*: S1 ('MetaSel ('Just "gcStatsWallSeconds") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Double))))))

secs :: Double -> String Source #

Convert a number of seconds to a string. The string will consist of four decimal places, followed by a short description of the time units.

measure Source #

Arguments

:: Benchmarkable

Operation to benchmark.

-> Int64

Number of iterations.

-> IO (Measured, Double) 

Measure the execution of a benchmark a given number of times.

This function initializes the timer before measuring time (refer to the documentation for initializeTime for more details).

runBenchmark Source #

Arguments

:: Benchmarkable 
-> Double

Lower bound on how long the benchmarking process should take. In practice, this time limit may be exceeded in order to generate enough data to perform meaningful statistical analyses.

-> IO (Vector Measured, Double) 

Run a single benchmark, and return measurements collected while executing it, along with the amount of time the measurement process took.

This function initializes the timer before measuring time (refer to the documentation for initializeTime for more details).

runBenchmarkable :: Benchmarkable -> Int64 -> (a -> a -> a) -> (Int64 -> IO () -> IO a) -> IO a Source #

measured :: Measured Source #

An empty structure.

applyGCStatistics Source #

Arguments

:: Maybe GCStatistics

Statistics gathered at the end of a run, post-GC.

-> Maybe GCStatistics

Statistics gathered at the end of a run, pre-GC.

-> Maybe GCStatistics

Statistics gathered at the beginning of a run.

-> Measured

Value to "modify".

-> Measured 

Apply the difference between two sets of GC statistics to a measurement.

threshold :: Double Source #

The amount of time a benchmark must run for in order for us to have some trust in the raw measurement.

We set this threshold so that we can generate enough data to later perform meaningful statistical analyses.

The threshold is 30 milliseconds. One use of runBenchmark must accumulate more than 300 milliseconds of total measurements above this threshold before it will finish.