-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Criterion measurement functionality and associated types
--   
--   Measurement-related functionality extracted from Criterion, with
--   minimal dependencies. The rationale for this is to enable alternative
--   analysis front-ends.
@package criterion-measurement
@version 0.2.2.0


-- | Exports <a>fakeEnvironment</a>.
module Criterion.Measurement.Types.Internal

-- | A dummy environment that is passed to functions that create benchmarks
--   from environments when no concrete environment is available.
fakeEnvironment :: env

-- | Generate a function which applies an argument to a function a given
--   number of times, reducing the result to normal form.
nf' :: (b -> ()) -> (a -> b) -> a -> Int64 -> IO ()

-- | Generate a function which applies an argument to a function a given
--   number of times.
whnf' :: (a -> b) -> a -> Int64 -> IO ()
data () => SPEC
SPEC :: SPEC
SPEC2 :: SPEC


-- | Types for benchmarking.
--   
--   The core type is <a>Benchmarkable</a>, which admits both pure
--   functions and <a>IO</a> actions.
--   
--   For a pure function of type <tt>a -&gt; b</tt>, the benchmarking
--   harness calls this function repeatedly, each time with a different
--   <a>Int64</a> argument (the number of times to run the function in a
--   loop), and reduces the result the function returns to weak head normal
--   form.
--   
--   For an action of type <tt>IO a</tt>, the benchmarking harness calls
--   the action repeatedly, but does not reduce the result.
module Criterion.Measurement.Types

-- | A pure function or impure action that can be benchmarked. The
--   <a>Int64</a> parameter indicates the number of times to run the given
--   function or action.
data Benchmarkable
Benchmarkable :: (Int64 -> IO a) -> (Int64 -> a -> IO ()) -> (a -> Int64 -> IO ()) -> Bool -> Benchmarkable
[allocEnv] :: Benchmarkable -> Int64 -> IO a
[cleanEnv] :: Benchmarkable -> Int64 -> a -> IO ()
[runRepeatedly] :: Benchmarkable -> a -> Int64 -> IO ()
[perRun] :: Benchmarkable -> Bool

-- | Specification of a collection of benchmarks and environments. A
--   benchmark may consist of:
--   
--   <ul>
--   <li>An environment that creates input data for benchmarks, created
--   with <a>env</a>.</li>
--   <li>A single <a>Benchmarkable</a> item with a name, created with
--   <a>bench</a>.</li>
--   <li>A (possibly nested) group of <a>Benchmark</a>s, created with
--   <a>bgroup</a>.</li>
--   </ul>
data Benchmark
[Environment] :: NFData env => IO env -> (env -> IO a) -> (env -> Benchmark) -> Benchmark
[Benchmark] :: String -> Benchmarkable -> Benchmark
[BenchGroup] :: String -> [Benchmark] -> Benchmark

-- | A collection of measurements made while benchmarking.
--   
--   Measurements related to garbage collection are tagged with <b>GC</b>.
--   They will only be available if a benchmark is run with <tt>"+RTS
--   -T"</tt>.
--   
--   <b>Packed storage.</b> When GC statistics cannot be collected, GC
--   values will be set to huge negative values. If a field is labeled with
--   "<b>GC</b>" below, use <a>fromInt</a> and <a>fromDouble</a> to safely
--   convert to "real" values.
data Measured
Measured :: !Double -> !Double -> !Int64 -> !Int64 -> !Int64 -> !Int64 -> !Int64 -> !Int64 -> !Double -> !Double -> !Double -> !Double -> Measured

-- | Total wall-clock time elapsed, in seconds.
[measTime] :: Measured -> !Double

-- | Total CPU time elapsed, in seconds. Includes both user and kernel
--   (system) time.
[measCpuTime] :: Measured -> !Double

-- | Cycles, in unspecified units that may be CPU cycles. (On i386 and
--   x86_64, this is measured using the <tt>rdtsc</tt> instruction.)
[measCycles] :: Measured -> !Int64

-- | Number of loop iterations measured.
[measIters] :: Measured -> !Int64

-- | <b>(GC)</b> Number of bytes allocated. Access using <a>fromInt</a>.
[measAllocated] :: Measured -> !Int64

-- | <b>(GC)</b> Max number of megabytes allocated. Access using
--   <a>fromInt</a>.
[measPeakMbAllocated] :: Measured -> !Int64

-- | <b>(GC)</b> Number of garbage collections performed. Access using
--   <a>fromInt</a>.
[measNumGcs] :: Measured -> !Int64

-- | <b>(GC)</b> Number of bytes copied during garbage collection. Access
--   using <a>fromInt</a>.
[measBytesCopied] :: Measured -> !Int64

-- | <b>(GC)</b> Wall-clock time spent doing real work ("mutation"), as
--   distinct from garbage collection. Access using <a>fromDouble</a>.
[measMutatorWallSeconds] :: Measured -> !Double

-- | <b>(GC)</b> CPU time spent doing real work ("mutation"), as distinct
--   from garbage collection. Access using <a>fromDouble</a>.
[measMutatorCpuSeconds] :: Measured -> !Double

-- | <b>(GC)</b> Wall-clock time spent doing garbage collection. Access
--   using <a>fromDouble</a>.
[measGcWallSeconds] :: Measured -> !Double

-- | <b>(GC)</b> CPU time spent doing garbage collection. Access using
--   <a>fromDouble</a>.
[measGcCpuSeconds] :: Measured -> !Double

-- | Convert a (possibly unavailable) GC measurement to a true value. If
--   the measurement is a huge negative number that corresponds to "no
--   data", this will return <a>Nothing</a>.
fromInt :: Int64 -> Maybe Int64

-- | Convert from a true value back to the packed representation used for
--   GC measurements.
toInt :: Maybe Int64 -> Int64

-- | Convert a (possibly unavailable) GC measurement to a true value. If
--   the measurement is a huge negative number that corresponds to "no
--   data", this will return <a>Nothing</a>.
fromDouble :: Double -> Maybe Double

-- | Convert from a true value back to the packed representation used for
--   GC measurements.
toDouble :: Maybe Double -> Double

-- | Field names and accessors for a <a>Measured</a> record.
measureAccessors :: Map String (Measured -> Maybe Double, String)

-- | Field names in a <a>Measured</a> record, in the order in which they
--   appear.
measureKeys :: [String]
measure :: Unbox a => (Measured -> a) -> Vector Measured -> Vector a

-- | Normalise every measurement as if <a>measIters</a> was 1.
--   
--   (<a>measIters</a> itself is left unaffected.)
rescale :: Measured -> Measured

-- | Run a benchmark (or collection of benchmarks) in the given
--   environment. The purpose of an environment is to lazily create input
--   data to pass to the functions that will be benchmarked.
--   
--   A common example of environment data is input that is read from a
--   file. Another is a large data structure constructed in-place.
--   
--   <b>Motivation.</b> In earlier versions of criterion, all benchmark
--   inputs were always created when a program started running. By
--   deferring the creation of an environment when its associated
--   benchmarks need the its, we avoid two problems that this strategy
--   caused:
--   
--   <ul>
--   <li>Memory pressure distorted the results of unrelated benchmarks. If
--   one benchmark needed e.g. a gigabyte-sized input, it would force the
--   garbage collector to do extra work when running some other benchmark
--   that had no use for that input. Since the data created by an
--   environment is only available when it is in scope, it should be
--   garbage collected before other benchmarks are run.</li>
--   <li>The time cost of generating all needed inputs could be significant
--   in cases where no inputs (or just a few) were really needed. This
--   occurred often, for instance when just one out of a large suite of
--   benchmarks was run, or when a user would list the collection of
--   benchmarks without running any.</li>
--   </ul>
--   
--   <b>Creation.</b> An environment is created right before its related
--   benchmarks are run. The <a>IO</a> action that creates the environment
--   is run, then the newly created environment is evaluated to normal form
--   (hence the <a>NFData</a> constraint) before being passed to the
--   function that receives the environment.
--   
--   <b>Complex environments.</b> If you need to create an environment that
--   contains multiple values, simply pack the values into a tuple.
--   
--   <b>Lazy pattern matching.</b> In situations where a "real" environment
--   is not needed, e.g. if a list of benchmark names is being generated, a
--   value which throws an exception will be passed to the function that
--   receives the environment. This avoids the overhead of generating an
--   environment that will not actually be used.
--   
--   The function that receives the environment must use lazy pattern
--   matching to deconstruct the tuple (e.g., <tt>~(x, y)</tt>, not <tt>(x,
--   y)</tt>), as use of strict pattern matching will cause a crash if an
--   exception-throwing value is passed in.
--   
--   <b>Example.</b> This program runs benchmarks in an environment that
--   contains two values. The first value is the contents of a text file;
--   the second is a string. Pay attention to the use of a lazy pattern to
--   deconstruct the tuple in the function that returns the benchmarks to
--   be run.
--   
--   <pre>
--   setupEnv = do
--     let small = replicate 1000 (1 :: Int)
--     big &lt;- map length . words &lt;$&gt; readFile "/usr/dict/words"
--     return (small, big)
--   
--   main = defaultMain [
--      -- notice the lazy pattern match here!
--      env setupEnv $ \ ~(small,big) -&gt; bgroup "main" [
--      bgroup "small" [
--        bench "length" $ whnf length small
--      , bench "length . filter" $ whnf (length . filter (==1)) small
--      ]
--    ,  bgroup "big" [
--        bench "length" $ whnf length big
--      , bench "length . filter" $ whnf (length . filter (==1)) big
--      ]
--    ] ]
--   </pre>
--   
--   <b>Discussion.</b> The environment created in the example above is
--   intentionally <i>not</i> ideal. As Haskell's scoping rules suggest,
--   the variable <tt>big</tt> is in scope for the benchmarks that use only
--   <tt>small</tt>. It would be better to create a separate environment
--   for <tt>big</tt>, so that it will not be kept alive while the
--   unrelated benchmarks are being run.
env :: NFData env => IO env -> (env -> Benchmark) -> Benchmark

-- | Same as <a>env</a>, but but allows for an additional callback to clean
--   up the environment. Resource clean up is exception safe, that is, it
--   runs even if the <a>Benchmark</a> throws an exception.
envWithCleanup :: NFData env => IO env -> (env -> IO a) -> (env -> Benchmark) -> Benchmark

-- | Create a Benchmarkable where a fresh environment is allocated for
--   every batch of runs of the benchmarkable.
--   
--   The environment is evaluated to normal form before the benchmark is
--   run.
--   
--   When using <a>whnf</a>, <a>whnfIO</a>, etc. Criterion creates a
--   <a>Benchmarkable</a> whichs runs a batch of <tt>N</tt> repeat runs of
--   that expressions. Criterion may run any number of these batches to get
--   accurate measurements. Environments created by <a>env</a> and
--   <a>envWithCleanup</a>, are shared across all these batches of runs.
--   
--   This is fine for simple benchmarks on static input, but when
--   benchmarking IO operations where these operations can modify (and
--   especially grow) the environment this means that later batches might
--   have their accuracy effected due to longer, for example, longer
--   garbage collection pauses.
--   
--   An example: Suppose we want to benchmark writing to a Chan, if we
--   allocate the Chan using environment and our benchmark consists of
--   <tt>writeChan env ()</tt>, the contents and thus size of the Chan will
--   grow with every repeat. If Criterion runs a 1,000 batches of 1,000
--   repeats, the result is that the channel will have 999,000 items in it
--   by the time the last batch is run. Since GHC GC has to copy the live
--   set for every major GC this means our last set of writes will suffer a
--   lot of noise of the previous repeats.
--   
--   By allocating a fresh environment for every batch of runs this
--   function should eliminate this effect.
perBatchEnv :: (NFData env, NFData b) => (Int64 -> IO env) -> (env -> IO b) -> Benchmarkable

-- | Same as <a>perBatchEnv</a>, but but allows for an additional callback
--   to clean up the environment. Resource clean up is exception safe, that
--   is, it runs even if the <a>Benchmark</a> throws an exception.
perBatchEnvWithCleanup :: (NFData env, NFData b) => (Int64 -> IO env) -> (Int64 -> env -> IO ()) -> (env -> IO b) -> Benchmarkable

-- | Create a Benchmarkable where a fresh environment is allocated for
--   every run of the operation to benchmark. This is useful for
--   benchmarking mutable operations that need a fresh environment, such as
--   sorting a mutable Vector.
--   
--   As with <a>env</a> and <a>perBatchEnv</a> the environment is evaluated
--   to normal form before the benchmark is run.
--   
--   This introduces extra noise and result in reduce accuracy compared to
--   other Criterion benchmarks. But allows easier benchmarking for mutable
--   operations than was previously possible.
perRunEnv :: (NFData env, NFData b) => IO env -> (env -> IO b) -> Benchmarkable

-- | Same as <a>perRunEnv</a>, but but allows for an additional callback to
--   clean up the environment. Resource clean up is exception safe, that
--   is, it runs even if the <a>Benchmark</a> throws an exception.
perRunEnvWithCleanup :: (NFData env, NFData b) => IO env -> (env -> IO ()) -> (env -> IO b) -> Benchmarkable

-- | Construct a <a>Benchmarkable</a> value from an impure action, where
--   the <a>Int64</a> parameter indicates the number of times to run the
--   action.
toBenchmarkable :: (Int64 -> IO ()) -> Benchmarkable

-- | Create a single benchmark.
bench :: String -> Benchmarkable -> Benchmark

-- | Group several benchmarks together under a common name.
bgroup :: String -> [Benchmark] -> Benchmark

-- | Add the given prefix to a name. If the prefix is empty, the name is
--   returned unmodified. Otherwise, the prefix and name are separated by a
--   <tt>'/'</tt> character.
addPrefix :: String -> String -> String

-- | Retrieve the names of all benchmarks. Grouped benchmarks are prefixed
--   with the name of the group they're in.
benchNames :: Benchmark -> [String]

-- | Apply an argument to a function, and evaluate the result to normal
--   form (NF).
nf :: NFData b => (a -> b) -> a -> Benchmarkable

-- | Apply an argument to a function, and evaluate the result to weak head
--   normal form (WHNF).
whnf :: (a -> b) -> a -> Benchmarkable

-- | Perform an action, then evaluate its result to normal form (NF). This
--   is particularly useful for forcing a lazy <a>IO</a> action to be
--   completely performed.
--   
--   If the construction of the 'IO a' value is an important factor in the
--   benchmark, it is best to use <a>nfAppIO</a> instead.
nfIO :: NFData a => IO a -> Benchmarkable

-- | Perform an action, then evaluate its result to weak head normal form
--   (WHNF). This is useful for forcing an <a>IO</a> action whose result is
--   an expression to be evaluated down to a more useful value.
--   
--   If the construction of the 'IO a' value is an important factor in the
--   benchmark, it is best to use <a>whnfAppIO</a> instead.
whnfIO :: IO a -> Benchmarkable

-- | Apply an argument to a function which performs an action, then
--   evaluate its result to normal form (NF). This function constructs the
--   'IO b' value on each iteration, similar to <a>nf</a>. This is
--   particularly useful for <a>IO</a> actions where the bulk of the work
--   is not bound by IO, but by pure computations that may optimize away if
--   the argument is known statically, as in <a>nfIO</a>.
nfAppIO :: NFData b => (a -> IO b) -> a -> Benchmarkable

-- | Perform an action, then evaluate its result to weak head normal form
--   (WHNF). This function constructs the 'IO b' value on each iteration,
--   similar to <a>whnf</a>. This is particularly useful for <a>IO</a>
--   actions where the bulk of the work is not bound by IO, but by pure
--   computations that may optimize away if the argument is known
--   statically, as in <a>nfIO</a>.
whnfAppIO :: (a -> IO b) -> a -> Benchmarkable
instance GHC.Generics.Generic Criterion.Measurement.Types.Measured
instance Data.Data.Data Criterion.Measurement.Types.Measured
instance GHC.Show.Show Criterion.Measurement.Types.Measured
instance GHC.Read.Read Criterion.Measurement.Types.Measured
instance GHC.Classes.Eq Criterion.Measurement.Types.Measured
instance GHC.Show.Show Criterion.Measurement.Types.Benchmark
instance Data.Aeson.Types.FromJSON.FromJSON Criterion.Measurement.Types.Measured
instance Data.Aeson.Types.ToJSON.ToJSON Criterion.Measurement.Types.Measured
instance Control.DeepSeq.NFData Criterion.Measurement.Types.Measured
instance Data.Binary.Class.Binary Criterion.Measurement.Types.Measured


-- | Benchmark measurement code.
module Criterion.Measurement

-- | Set up time measurement.
--   
--   <tt>criterion</tt> 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
--   <a>initializeTime</a> accomplishes) before one can actually measure
--   the current time (which <a>getTime</a> accomplishes).
--   
--   It is imperative that you call <a>initializeTime</a> before calling
--   <a>getTime</a>. (See <a>this bug report</a> for an example of what can
--   happen if you do not do so.) All of the <a>IO</a>-returning functions
--   in <a>Criterion.Main</a> make sure that this is done, but other
--   functions (such as those in <a>Criterion.Measurement</a>) do not
--   guarantee this unless otherwise stated.
initializeTime :: IO ()

-- | Return the current wallclock time, in seconds since some arbitrary
--   time.
--   
--   You <i>must</i> call <a>initializeTime</a> once before calling this
--   function! Refer to the documentation for <a>initializeTime</a> for
--   more details.
getTime :: IO Double

-- | Return the amount of elapsed CPU time, combining user and kernel
--   (system) time into a single measure.
getCPUTime :: IO Double

-- | Read the CPU cycle counter.
getCycles :: IO Word64

-- | Try to get GC statistics, bearing in mind that the GHC runtime will
--   throw an exception if statistics collection was not enabled using
--   "<tt>+RTS -T</tt>".
--   
--   If you need guaranteed up-to-date stats, call <a>performGC</a> first.
getGCStatistics :: IO (Maybe GCStatistics)

-- | Statistics about memory usage and the garbage collector. Apart from
--   <a>gcStatsCurrentBytesUsed</a> and <a>gcStatsCurrentBytesSlop</a> all
--   are cumulative values since the program started.
--   
--   <a>GCStatistics</a> is cargo-culted from the <tt>GCStats</tt> data
--   type that <a>GHC.Stats</a> used to export. Since <tt>GCStats</tt> was
--   removed in GHC 8.4, <tt>criterion</tt> uses <a>GCStatistics</a> to
--   provide a backwards-compatible view of GC statistics.
data GCStatistics
GCStatistics :: !Int64 -> !Int64 -> !Int64 -> !Int64 -> !Int64 -> !Int64 -> !Int64 -> !Int64 -> !Int64 -> !Int64 -> !Double -> !Double -> !Double -> !Double -> !Double -> !Double -> GCStatistics

-- | Total number of bytes allocated
[gcStatsBytesAllocated] :: GCStatistics -> !Int64

-- | Number of garbage collections performed (any generation, major and
--   minor)
[gcStatsNumGcs] :: GCStatistics -> !Int64

-- | Maximum number of live bytes seen so far
[gcStatsMaxBytesUsed] :: GCStatistics -> !Int64

-- | Number of byte usage samples taken, or equivalently the number of
--   major GCs performed.
[gcStatsNumByteUsageSamples] :: GCStatistics -> !Int64

-- | Sum of all byte usage samples, can be used with
--   <a>gcStatsNumByteUsageSamples</a> to calculate averages with arbitrary
--   weighting (if you are sampling this record multiple times).
[gcStatsCumulativeBytesUsed] :: GCStatistics -> !Int64

-- | Number of bytes copied during GC
[gcStatsBytesCopied] :: GCStatistics -> !Int64

-- | Number of live bytes at the end of the last major GC
[gcStatsCurrentBytesUsed] :: GCStatistics -> !Int64

-- | Current number of bytes lost to slop
[gcStatsCurrentBytesSlop] :: GCStatistics -> !Int64

-- | Maximum number of bytes lost to slop at any one time so far
[gcStatsMaxBytesSlop] :: GCStatistics -> !Int64

-- | Maximum number of megabytes allocated
[gcStatsPeakMegabytesAllocated] :: GCStatistics -> !Int64

-- | CPU time spent running mutator threads. This does not include any
--   profiling overhead or initialization.
[gcStatsMutatorCpuSeconds] :: GCStatistics -> !Double

-- | Wall clock time spent running mutator threads. This does not include
--   initialization.
[gcStatsMutatorWallSeconds] :: GCStatistics -> !Double

-- | CPU time spent running GC
[gcStatsGcCpuSeconds] :: GCStatistics -> !Double

-- | Wall clock time spent running GC
[gcStatsGcWallSeconds] :: GCStatistics -> !Double

-- | Total CPU time elapsed since program start
[gcStatsCpuSeconds] :: GCStatistics -> !Double

-- | Total wall clock time elapsed since start
[gcStatsWallSeconds] :: GCStatistics -> !Double

-- | 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.
secs :: Double -> String

-- | Measure the execution of a benchmark a given number of times.
--   
--   This function initializes the timer before measuring time (refer to
--   the documentation for <a>initializeTime</a> for more details).
measure :: Benchmarkable -> Int64 -> IO (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 <a>initializeTime</a> for more details).
runBenchmark :: Benchmarkable -> Double -> IO (Vector Measured, Double)
runBenchmarkable :: Benchmarkable -> Int64 -> (a -> a -> a) -> (Int64 -> IO () -> IO a) -> IO a
runBenchmarkable_ :: Benchmarkable -> Int64 -> IO ()

-- | An empty structure.
measured :: Measured

-- | Apply the difference between two sets of GC statistics to a
--   measurement.
applyGCStatistics :: Maybe GCStatistics -> Maybe GCStatistics -> Maybe GCStatistics -> Measured -> Measured

-- | 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 <a>runBenchmark</a> must
--   accumulate more than 300 milliseconds of total measurements above this
--   threshold before it will finish.
threshold :: Double
instance GHC.Generics.Generic Criterion.Measurement.GCStatistics
instance Data.Data.Data Criterion.Measurement.GCStatistics
instance GHC.Show.Show Criterion.Measurement.GCStatistics
instance GHC.Read.Read Criterion.Measurement.GCStatistics
instance GHC.Classes.Eq Criterion.Measurement.GCStatistics
