Criterion

https://hackage.haskell.org/package/criterion-1.6.4.1/docs/
Admin
Criterion is a powerful benchmarking library for Haskell that helps measure and analyze the...
Tokens:41,009
Snippets:249
Trust Score:9.7
Update:11 months ago
Show doc for...
Tokens:
Raw
### Create Environment with Setup and Cleanup - Haskell Criterion

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

The envWithCleanup function creates a benchmark environment with both setup and cleanup phases. It takes an IO action for setup, a cleanup function, and a function to create the Benchmark. This ensures proper resource management in benchmarks.

```haskell
envWithCleanup :: NFData env => IO env -> (env -> IO a) -> (env -> Benchmark) -> Benchmark
```

--------------------------------

### Create Environment with Setup - Haskell Criterion Benchmarking

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

The env function creates a benchmark environment with setup. It takes an IO action that produces an NFData-constrained environment and a function that uses that environment to create a Benchmark. The environment is set up once and reused across benchmark runs.

```haskell
env :: NFData env => IO env -> (env -> Benchmark) -> Benchmark
```

--------------------------------

### Per-Batch Environment with Cleanup - Haskell Criterion

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

The perBatchEnvWithCleanup function manages per-batch environment setup and cleanup. It takes a setup function based on batch size, a cleanup function, and an IO action using the environment. Both env and result must be NFData-constrained.

```haskell
perBatchEnvWithCleanup :: (NFData env, NFData b) => (Int64 -> IO env) -> (Int64 -> env -> IO ()) -> (env -> IO b) -> Benchmarkable
```

--------------------------------

### Setup Benchmark Environment with Lazy Pattern Matching - Haskell

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

Creates a benchmark environment containing multiple values (tuple) and demonstrates proper lazy pattern matching syntax (~(x, y)) to avoid crashes when exception-throwing values are passed. The example reads file contents and creates benchmark groups for small and large datasets.

```haskell
setupEnv = do
  let small = replicate 1000 (1 :: Int)
  big <- map length . words <$> readFile "/usr/dict/words"
  return (small, big)

main = defaultMain [
   -- notice the lazy pattern match here!
   env setupEnv $ \ ~(small,big) -> 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
   ]
 ] ]
```

--------------------------------

### Per-Run Environment Setup - Haskell Criterion Benchmarking

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

The perRunEnv function creates a fresh environment for each benchmark run. It takes an IO action for environment creation and an IO action using that environment to produce a Benchmarkable. Both env and result must satisfy NFData constraints.

```haskell
perRunEnv :: (NFData env, NFData b) => IO env -> (env -> IO b) -> Benchmarkable
```

--------------------------------

### Example: Benchmarking a Pure Function with Criterion

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main

An example demonstrating how to benchmark a pure Haskell function `firstN` using the `nf` function from Criterion. The function `firstN` is applied to the argument `1000` to create a `Benchmarkable` value.

```haskell
firstN :: Int -> [Int]
firstN k = take k [(0::Int).. ]

nf firstN 1000
```

--------------------------------

### Per-Batch Environment Setup - Haskell Criterion Benchmarking

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

The perBatchEnv function sets up environment per batch of benchmark runs. It takes a function that creates an environment based on batch size (Int64), an IO action using that environment, and produces a Benchmarkable. Both env and the result must satisfy NFData constraints.

```haskell
perBatchEnv :: (NFData env, NFData b) => (Int64 -> IO env) -> (env -> IO b) -> Benchmarkable
```

--------------------------------

### Run Benchmark Suite with defaultMain (Haskell)

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main

The `defaultMain` function serves as an entry point for running a suite of benchmarks, acting as a `main` function. It takes a list of `Benchmark` objects. The example demonstrates setting up a benchmark group for a Fibonacci function using `whnf` to evaluate to weak head normal form.

```haskell
import Criterion.Main

fib :: Int -> Int
fib 0 = 0
fib 1 = 1
fib n = fib (n-1) + fib (n-2)

main = defaultMain [
       bgroup "fib" [ bench "10" $ whnf fib 10
                    , bench "35" $ whnf fib 35
                    , bench "37" $ whnf fib 37
                    ]
                   ]

```

--------------------------------

### Run Configurable Benchmark Suite with defaultMainWith (Haskell)

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main

Use `defaultMainWith` to run benchmarks with custom configurations. This function takes a `Config` object and a list of `Benchmark`s. The example shows how to modify the default configuration to change the number of resamples for bootstrapping.

```haskell
import Criterion.Main.Options
import Criterion.Main

myConfig = defaultConfig {
              -- Resample 10 times for bootstrapping
              resamples = 10
           }

main = defaultMainWith myConfig [
         bench "fib 30" $ whnf fib 30
       ]

```

--------------------------------

### Per-Run Environment with Cleanup - Haskell Criterion

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

The perRunEnvWithCleanup function creates a fresh environment for each run with cleanup. It takes environment setup and cleanup IO actions, and a function using the environment. Both env and result must be NFData-constrained for proper evaluation.

```haskell
perRunEnvWithCleanup :: (NFData env, NFData b) => IO env -> (env -> IO ()) -> (env -> IO b) -> Benchmarkable
```

--------------------------------

### Benchmarking IO Actions (Normal Form) in Haskell

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/package/criterion

Provides an example of benchmarking an IO action using 'nfIO'. This function ensures that the result of the IO action is evaluated to normal form (fully evaluated) after execution. It's crucial for preventing resource leaks with lazy IO and ensuring complete evaluation.

```haskell
import Criterion.Main

main = defaultMain [
    bench "readFile" $ nfIO (readFile "GoodReadFile.hs")
  ]


```

```haskell
nfIO :: NFData a => IO a -> Benchmarkable

```

--------------------------------

### Benchmark weak head normal form evaluation with whnf in Haskell

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main

Demonstrates using the `whnf` function to benchmark pure function evaluation to weak head normal form. This example shows how `whnf firstN 1000` only evaluates the result until it reaches WHNF, which means it benchmarks only the production of the first list element rather than all 1000 elements as might be expected.

```haskell
whnf firstN 1000
```

--------------------------------

### Criterion Configuration Parsing (Haskell)

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main-Options

Provides functions for parsing command-line arguments and configuration for Criterion benchmarks. Includes functions for setting default configurations, parsing modes, and describing parser information.

```haskell
defaultConfig :: Config
-- | Default benchmarking configuration.

parseWith :: Config -> Parser Mode
-- | Parse a command line.

config :: Config -> Parser Config
-- | Parse a configuration.

describe :: Config -> ParserInfo Mode
-- | Flesh out a command-line parser.

describeWith :: Parser a -> ParserInfo a
-- | Flesh out command-line information using a custom `Parser`.

versionInfo :: String
-- | A string describing the version of this benchmark (really, the version of criterion that was used to build it).

```

--------------------------------

### Default Configuration and Parsing Functions (Haskell)

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main-Options

Provides the default configuration for Criterion benchmarks and functions to parse command-line arguments into different configuration modes. It includes functions for describing the parser.

```haskell
defaultConfig :: Config
parseWith :: Config -> Parser Mode
config :: Config -> Parser Config
describe :: Config -> ParserInfo Mode
describeWith :: Parser a -> ParserInfo a
versionInfo :: String
```

--------------------------------

### Getting Template Directory

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Report

A utility function to retrieve the path for template and report files. If the `-fembed-data-files` Cabal flag is active, it returns an empty path, indicating that files are embedded.

```haskell
getTemplateDir :: IO FilePath
-- Returns empty path if -fembed-data-files is enabled.
```

--------------------------------

### Benchmark Data Type Definition

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Types

Defines the Benchmark data type, used for specifying collections of benchmarks. It can represent an environment setup, a single benchmarkable item with a name, or a group of nested benchmarks.

```haskell
data Benchmark

-- Constructors for Benchmark
Environment :: forall env a. NFData env => IO env -> (env -> IO a) -> (env -> Benchmark) -> Benchmark
Benchmark :: String -> Benchmarkable -> Benchmark
BenchGroup :: String -> [Benchmark] -> Benchmark

-- Show instance for Benchmark
-- instances Show Benchmark
-- showsPrec :: Int -> Benchmark -> ShowS
-- show :: Benchmark -> String
-- showList :: [Benchmark] -> ShowS
```

--------------------------------

### Get Template Directory Path - Haskell

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Report

Retrieves the file path to the template directory used by Criterion for report rendering. Returns an IO FilePath that points to where default and custom templates are stored.

```haskell
getTemplateDir :: IO FilePath
```

--------------------------------

### Haskell: Benchmarkable Type Definition

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Types

Defines the `Benchmarkable` type, which represents actions that can be benchmarked. It supports both pure functions and IO actions, with options for environment setup, cleanup, and controlling evaluation depth (NFData or WHNF).

```haskell
data Benchmarkable = NFData a => Benchmarkable {
    allocEnv :: Int64 -> IO a
  , cleanEnv :: Int64 -> a -> IO ()
  , runRepeatedly :: a -> Int64 -> IO ()
  , perRun :: Bool
}

-- Helper functions for creating Benchmarkable actions:
toBenchmarkable :: (Int64 -> IO ()) -> Benchmarkable
nf :: NFData b => (a -> b) -> a -> Benchmarkable
whnf :: (a -> b) -> a -> Benchmarkable
nfIO :: NFData a => IO a -> Benchmarkable
whnfIO :: IO a -> Benchmarkable
nfAppIO :: NFData b => (a -> IO b) -> a -> Benchmarkable
whnfAppIO :: (a -> IO b) -> a -> Benchmarkable
```

--------------------------------

### Run Criterion Benchmark via Cabal with Output Report

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/package/criterion

Shell commands demonstrating how to execute a Criterion benchmark program using cabal run. The first command displays console output with statistical analysis, while the second command uses the --output flag to generate an HTML report file with interactive charts and detailed statistics.

```bash
$ cabal run Fibber.hs
benchmarking fib/1
time                 13.77 ns   (13.49 ns .. 14.07 ns)
                     0.998 R²   (0.997 R² .. 1.000 R²)
mean                 13.56 ns   (13.49 ns .. 13.70 ns)
std dev              305.1 ps   (64.14 ps .. 532.5 ps)
variance introduced by outliers: 36% (moderately inflated)

benchmarking fib/5
time                 173.9 ns   (172.8 ns .. 175.6 ns)
                     1.000 R²   (0.999 R² .. 1.000 R²)
mean                 173.8 ns   (173.1 ns .. 175.4 ns)
std dev              3.149 ns   (1.842 ns .. 5.954 ns)
variance introduced by outliers: 23% (moderately inflated)

benchmarking fib/9
time                 1.219 μs   (1.214 μs .. 1.228 μs)
                     1.000 R²   (1.000 R² .. 1.000 R²)
mean                 1.219 μs   (1.216 μs .. 1.223 μs)
std dev              12.43 ns   (9.907 ns .. 17.29 ns)

benchmarking fib/11
time                 3.253 μs   (3.246 μs .. 3.260 μs)
                     1.000 R²   (1.000 R² .. 1.000 R²)
mean                 3.248 μs   (3.243 μs .. 3.254 μs)
std dev              18.94 ns   (16.57 ns .. 21.95 ns)
```

```bash
$ cabal run Fibber.hs -- --output fibber.html
...similar output as before...
```

--------------------------------

### Benchmark Suite Structure in Haskell

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/package/criterion

Demonstrates the basic structure of a benchmark suite using Criterion. It shows how to group related benchmarks using 'bgroup' and define individual benchmarks using 'bench'. This forms the foundation for organizing and running benchmarks.

```haskell
main = defaultMain [
  bgroup "fib" [
    bench "1"  $ whnf fib 1
  , bench "5"  $ whnf fib 5
  , bench "9"  $ whnf fib 9
  , bench "11" $ whnf fib 11
  ]
  ]


```

--------------------------------

### Compile and Run Criterion Benchmark (Shell)

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main

This snippet shows the command to compile a Haskell benchmark file using GHC with optimization enabled. It also indicates how to run the compiled executable with help flags to see available command-line options.

```shell
ghc -O --make Fib
./Fib --help

```

--------------------------------

### defaultMain - Basic Benchmark Entry Point

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main

An entry point that can be used as a main function for benchmark programs. Executes benchmarks with default configuration.

```APIDOC
## defaultMain

### Description
An entry point that can be used as a main function. Runs a suite of benchmarks with default configuration.

### Signature
```haskell
defaultMain :: [Benchmark] -> IO ()
```

### Parameters
- **benchmarks** ([Benchmark]) - Required - List of benchmarks to run

### Returns
- **IO ()** - Performs IO operations to run benchmarks

### Usage Example
```haskell
import Criterion.Main

fib :: Int -> Int
fib 0 = 0
fib 1 = 1
fib n = fib (n-1) + fib (n-2)

main = defaultMain [
  bgroup "fib" [ bench "10" $ whnf fib 10
               , bench "35" $ whnf fib 35
               , bench "37" $ whnf fib 37
               ]
]
```
```

--------------------------------

### defaultMainWith - Configurable Benchmark Entry Point

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main

An entry point that can be used as a main function with customizable benchmarking configuration. Allows overriding default settings like resampling.

```APIDOC
## defaultMainWith

### Description
An entry point that can be used as a main function, with configurable defaults. Allows customization of benchmarking parameters.

### Signature
```haskell
defaultMainWith :: Config -> [Benchmark] -> IO ()
```

### Parameters
- **config** (Config) - Required - Benchmarking configuration
- **benchmarks** ([Benchmark]) - Required - List of benchmarks to run

### Returns
- **IO ()** - Performs IO operations to run benchmarks

### Usage Example
```haskell
import Criterion.Main.Options
import Criterion.Main

fib :: Int -> Int
fib 0 = 0
fib 1 = 1
fib n = fib (n-1) + fib (n-2)

myConfig = defaultConfig {
  resamples = 10  -- Resample 10 times for bootstrapping
}

main = defaultMainWith myConfig [
  bench "fib 30" $ whnf fib 30
]
```

### Compilation
```bash
ghc -O --make Fib
```

### Execution
```bash
./Fib --help  # Display command line options
```
```

--------------------------------

### Interactive Benchmarking - Haskell

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

Functions for running benchmarks interactively. `benchmark` and `benchmarkWith` run a benchmark and analyze its performance. `benchmark'` and `benchmarkWith'` additionally return the analysis report. `benchmarkWith` and `benchmarkWith'` allow configuration of the benchmark run.

```haskell
benchmark :: Benchmarkable -> IO ()
benchmarkWith :: Config -> Benchmarkable -> IO ()
benchmark' :: Benchmarkable -> IO Report
benchmarkWith' :: Config -> Benchmarkable -> IO Report
```

--------------------------------

### makeMatcher - Benchmark Name Matching

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main

Create a function that matches benchmark names against command line arguments. Useful for filtering which benchmarks to run.

```APIDOC
## makeMatcher

### Description
Create a function that can tell if a name given on the command line matches a benchmark.

### Signature
```haskell
makeMatcher :: MatchType -> [String] -> Either String (String -> Bool)
```

### Parameters
- **matchType** (MatchType) - Required - The matching strategy to use
- **arguments** ([String]) - Required - Command line arguments for pattern matching

### Returns
- **Either String (String -> Bool)** - Either an error message or a predicate function

### Notes
Useful for filtering benchmarks based on command line patterns.
```

--------------------------------

### Create Per-Run Environment with Cleanup in Haskell

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

Constructs a Benchmarkable that allocates a fresh environment for each individual run with exception-safe resource cleanup. Similar to perRunEnv but includes a cleanup callback that executes even if the benchmark throws an exception. Enables reliable benchmarking of mutable operations with guaranteed resource deallocation.

```Haskell
perRunEnvWithCleanup :: (NFData env, NFData b)
  => IO env
  -> (env -> IO ())
  -> (env -> IO b)
  -> Benchmarkable
```

--------------------------------

### Run Benchmark with Config and Return Report - Haskell Criterion

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

The benchmarkWith' function runs a Benchmarkable with custom Config and returns a Report. It takes a Config and Benchmarkable, returning an IO action yielding detailed results for programmatic use.

```haskell
benchmarkWith' :: Config -> Benchmarkable -> IO Report
```

--------------------------------

### Benchmark IO Actions with Criterion

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main

Benchmark IO actions using `nfIO` (fully evaluate) or `whnfIO` (weak head normal form). Variants `nfAppIO` and `whnfAppIO` are available when the input argument needs to be passed separately, useful when the bulk of the work is not IO-bound.

```haskell
nfIO   :: NFData a => IO a -> Benchmarkable
whnfIO ::               IO a -> Benchmarkable

nfAppIO   :: NFData b => (a -> IO b) -> a -> Benchmarkable
whnfAppIO ::               (a -> IO b) -> a -> Benchmarkable
```

--------------------------------

### defaultConfig - Default Configuration

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main

The default benchmarking configuration used by Criterion. Can be customized by creating a new Config record.

```APIDOC
## defaultConfig

### Description
Default benchmarking configuration provided by Criterion. Use this as a base when creating custom configurations.

### Signature
```haskell
defaultConfig :: Config
```

### Type
- **Config** - A record type containing benchmarking parameters

### Common Configuration Fields
- **resamples** (Int) - Number of bootstrap resamples to perform
- Other timing and reporting parameters

### Usage Example
```haskell
myConfig = defaultConfig {
  resamples = 10
}
```
```

--------------------------------

### OutlierEffect: Binary Serialization Instances

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Analysis

Provides instances for binary serialization and deserialization of `OutlierEffect` using the `binary` package. This allows for efficient storage and transmission of `OutlierEffect` data.

```haskell
instance Binary OutlierEffect where
  put :: OutlierEffect -> Put
  get :: Get OutlierEffect
```

--------------------------------

### Run Benchmark with Default Configuration - Haskell Criterion

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

The benchmark function runs a Benchmarkable using default Criterion configuration. It takes a Benchmarkable and returns an IO action that performs the measurement and displays results.

```haskell
benchmark :: Benchmarkable -> IO ()
```

--------------------------------

### Benchmarking IO Actions (Weak Head Normal Form) in Haskell

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/package/criterion

Demonstrates benchmarking an IO action using 'whnfIO'. This function evaluates the IO action's result only to weak head normal form (WHNF), meaning only the outermost constructor is evaluated. This is useful for simple return values or when evaluating the outermost constructor is sufficient.

```haskell
whnfIO :: IO a -> Benchmarkable

```

--------------------------------

### Show Instance for Config in Criterion

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Types

The Show instance for Config provides a way to convert Config values into human-readable String representations. It includes functions such as showsPrec, show, and showList, which are essential for debugging, logging, and displaying configuration settings. The output format is designed for clarity.

```haskell
showsPrec :: Int -> Config -> ShowS
show :: Config -> String
showList :: [Config] -> ShowS
```

--------------------------------

### Benchmark IO Function to Weak Head Normal Form - Haskell

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

The whnfAppIO function benchmarks an IO-returning function by evaluating its result to weak head normal form. It takes a function returning an IO action and its argument, producing a Benchmarkable.

```haskell
whnfAppIO :: (a -> IO b) -> a -> Benchmarkable
```

--------------------------------

### Create Per-Batch Environment with Cleanup in Haskell

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

Constructs a Benchmarkable that allocates a fresh environment for each batch of benchmark runs, with exception-safe resource cleanup. The environment is evaluated to normal form before execution. This approach prevents accumulated side effects (like growing data structures) from affecting measurement accuracy across multiple batches.

```Haskell
perBatchEnvWithCleanup :: (NFData env, NFData b)
  => (Int64 -> IO env)
  -> (Int64 -> env -> IO ())
  -> (env -> IO b)
  -> Benchmarkable
```

--------------------------------

### Create Fibonacci Benchmark with Criterion in Haskell

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/package/criterion

A complete benchmark program measuring the performance of a recursive Fibonacci function using Criterion. The code defines the fib function and creates a benchmark harness using defaultMain with multiple test cases (fib 1, 5, 9, 11). Requires base and criterion packages via Cabal.

```haskell
{- cabal:
build-depends: base, criterion
-}

import Criterion.Main

-- The function we're benchmarking.
fib :: Int -> Int
fib m | m < 0     = error "negative!"
      | otherwise = go m
  where
    go 0 = 0
    go 1 = 1
    go n = go (n - 1) + go (n - 2)

-- Our benchmark harness.
main = defaultMain [
  bgroup "fib" [ bench "1"  $ whnf fib 1
               , bench "5"  $ whnf fib 5
               , bench "9"  $ whnf fib 9
               , bench "11" $ whnf fib 11
               ]
  ]
```

--------------------------------

### Run Benchmark with Custom Configuration - Haskell Criterion

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

The benchmarkWith function runs a Benchmarkable using a custom Config. It takes a Config and Benchmarkable, returning an IO action that performs the measurement with specified settings.

```haskell
benchmarkWith :: Config -> Benchmarkable -> IO ()
```

--------------------------------

### OutlierEffect: Generic Programming Instances

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Analysis

Details the `Generic` instance for `OutlierEffect`, enabling generic programming capabilities. This includes instances for `GHC.Generics` like `Rep`, `from`, and `to`, allowing for metaprogramming and deriving other type classes.

```haskell
instance Generic OutlierEffect where
  type Rep OutlierEffect = D1 ('MetaData "OutlierEffect" "Criterion.Types" "criterion-1.6.4.1-K8urswSQARiCV3c9gCG1B5" 'False) ((C1 ('MetaCons "Unaffected" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Slight" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "Moderate" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Severe" 'PrefixI 'False) (U1 :: Type -> Type)))
  from :: OutlierEffect -> Rep OutlierEffect x
  to :: Rep OutlierEffect x -> OutlierEffect
```

--------------------------------

### Create Per-Run Environment in Haskell

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

Constructs a Benchmarkable that allocates a fresh environment for each individual run of the benchmark operation. Useful for benchmarking mutable operations requiring clean state. The environment is evaluated to normal form before benchmarking. Introduces additional noise compared to shared environment benchmarks but enables accurate measurement of stateful operations.

```Haskell
perRunEnv :: (NFData env, NFData b)
  => IO env
  -> (env -> IO b)
  -> Benchmarkable
```

--------------------------------

### Defining Benchmark Groups in Haskell

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/package/criterion

Illustrates the use of the 'bgroup' function in Criterion to organize benchmarks into logical groups. The 'bgroup' function takes a group name (String) and a list of benchmarks (Benchmark) as arguments, returning a single Benchmark.

```haskell
bgroup :: String -> [Benchmark] -> Benchmark

```

--------------------------------

### Haskell: SampleAnalysis Typeclass Instances

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Analysis

Details the implementation of various typeclasses for the SampleAnalysis data type in the Criterion library. This includes serialization (FromJSON, ToJSON), generic programming (Generic), input/output (Read, Show, Binary), strictness (NFData), and equality (Eq). These instances are crucial for data handling, persistence, and comparison within the Criterion package.

```haskell
Instance detailsDefined in Criterion.Types MethodsparseJSON :: Value -> Parser SampleAnalysis #parseJSONList :: Value -> Parser [SampleAnalysis] #omittedField :: Maybe SampleAnalysis #
```

```haskell
Instance detailsDefined in Criterion.Types MethodstoJSON :: SampleAnalysis -> Value #toEncoding :: SampleAnalysis -> Encoding #toJSONList :: [SampleAnalysis] -> Value #toEncodingList :: [SampleAnalysis] -> Encoding #omitField :: SampleAnalysis -> Bool #
```

```haskell
Instance detailsDefined in Criterion.Types Associated Types| type Rep SampleAnalysis|   
---
Instance detailsDefined in Criterion.Types type Rep SampleAnalysis = D1 ('MetaData "SampleAnalysis" "Criterion.Types" "criterion-1.6.4.1-K8urswSQARiCV3c9gCG1B5" 'False) (C1 ('MetaCons "SampleAnalysis" 'PrefixI 'True) ((S1 ('MetaSel ('Just "anRegress") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Regression]) :*: S1 ('MetaSel ('Just "anMean") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Estimate ConfInt Double))) :*: (S1 ('MetaSel ('Just "anStdDev") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Estimate ConfInt Double)) :*: S1 ('MetaSel ('Just "anOutlierVar") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 OutlierVariance))))  
Methods
from :: SampleAnalysis -> Rep SampleAnalysis x #
to :: Rep SampleAnalysis x -> SampleAnalysis #
```

```haskell
Instance detailsDefined in Criterion.Types MethodsreadsPrec :: Int -> ReadS SampleAnalysis #readList :: ReadS [SampleAnalysis] #readPrec :: ReadPrec SampleAnalysis #readListPrec :: ReadPrec [SampleAnalysis] #
```

```haskell
Instance detailsDefined in Criterion.Types MethodsshowsPrec :: Int -> SampleAnalysis -> ShowS #show :: SampleAnalysis -> String #showList :: [SampleAnalysis] -> ShowS #
```

```haskell
Instance detailsDefined in Criterion.Types Methodsput :: SampleAnalysis -> Put #get :: Get SampleAnalysis #putList :: [SampleAnalysis] -> Put #
```

```haskell
Instance detailsDefined in Criterion.Types Methodsrnf :: SampleAnalysis -> () #
```

```haskell
Instance detailsDefined in Criterion.Types Methods(==) :: SampleAnalysis -> SampleAnalysis -> Bool #(/=) :: SampleAnalysis -> SampleAnalysis -> Bool #
```

--------------------------------

### Criterion Mode Read/Show/Eq Instances

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main-Options

Defines the Read, Show, and Eq instances for the 'Mode' data type. These instances allow 'Mode' values to be parsed from strings, converted to strings, and compared for equality, respectively.

```haskell
readsPrec :: Int -> ReadS Mode
readList :: ReadS [Mode]
readPrec :: ReadPrec Mode
readListPrec :: ReadPrec [Mode]
```

```haskell
showsPrec :: Int -> Mode -> ShowS
show :: Mode -> String
showList :: [Mode] -> ShowS
```

```haskell
(==) :: Mode -> Mode -> Bool
(/=) :: Mode -> Mode -> Bool
```

--------------------------------

### whnfIO - Weak Head Normal Form IO Evaluation

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main

Perform an IO action and evaluate its result to weak head normal form (WHNF). Useful for benchmarking IO actions with lighter evaluation.

```APIDOC
## whnfIO

### Description
Perform an action, then evaluate its result to weak head normal form (WHNF). This is useful for forcing an IO action whose result is an expression to be evaluated.

### Signature
```haskell
whnfIO :: IO a -> Benchmarkable
```

### Parameters
- **action** (IO a) - Required - The IO action to benchmark

### Returns
- **Benchmarkable** - A benchmark that can be executed

### Notes
If the construction of the IO a value is an important factor in the benchmark, consider using whnfAppIO instead.
```

--------------------------------

### Search Functionality Shortcuts (Haskell)

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Analysis

Provides keyboard shortcuts for the search functionality within the Criterion package documentation. These shortcuts allow users to efficiently find exported types, constructors, classes, functions, or patterns by name.

```haskell
Key| Shortcut
---|---
s| Open this search box
esc| Close this search box
↓,ctrl + j| Move down in search results
↑,ctrl + k| Move up in search results
↵| Go to active search result
```

--------------------------------

### Load Template from File Paths - Haskell

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Report

Loads a Mustache template from a list of candidate file paths. Searches through the provided directories for the specified template file and returns the template content as Text, raising TemplateNotFound if no match is located.

```haskell
loadTemplate :: [FilePath] -> FilePath -> IO Text
```

--------------------------------

### MatchType Data Type Instances (Haskell)

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main-Options

Defines various type class instances for the MatchType data type in Criterion.Main.Options. These instances enable operations such as pattern matching, bounded enumeration, generic programming, reading/showing, and equality/ordering comparisons.

```haskell
instance Data MatchType where
  gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> MatchType -> c MatchType
  gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c MatchType
  toConstr :: MatchType -> Constr
  dataTypeOf :: MatchType -> DataType
  dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c MatchType)
  dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c MatchType)
  gmapT :: (forall b. Data b => b -> b) -> MatchType -> MatchType
  gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> MatchType -> r
  gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> MatchType -> r
  gmapQ :: (forall d. Data d => d -> u) -> MatchType -> [u]
  gmapQi :: Int -> (forall d. Data d => d -> u) -> MatchType -> u
  gmapM :: Monad m => (forall d. Data d => d -> m d) -> MatchType -> m MatchType
  gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> MatchType -> m MatchType
  gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> MatchType -> m MatchType

instance Bounded MatchType where
  minBound :: MatchType
  maxBound :: MatchType

instance Enum MatchType where
  succ :: MatchType -> MatchType
  pred :: MatchType -> MatchType
  toEnum :: Int -> MatchType
  fromEnum :: MatchType -> Int
  enumFrom :: MatchType -> [MatchType]
  enumFromThen :: MatchType -> MatchType -> [MatchType]
  enumFromTo :: MatchType -> MatchType -> [MatchType]
  enumFromThenTo :: MatchType -> MatchType -> MatchType -> [MatchType]

instance Generic MatchType where
  type Rep MatchType = D1 ('MetaData "MatchType" "Criterion.Main.Options" "criterion-1.6.4.1-K8urswSQARiCV3c9gCG1B5" 'False) ((C1 ('MetaCons "Prefix" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Glob" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "Pattern" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "IPattern" 'PrefixI 'False) (U1 :: Type -> Type)))
  from :: MatchType -> Rep MatchType x
  to :: Rep MatchType x -> MatchType

instance Read MatchType where
  readsPrec :: Int -> ReadS MatchType
  readList :: ReadS [MatchType]
  readPrec :: ReadPrec MatchType
  readListPrec :: ReadPrec [MatchType]

instance Show MatchType where
  showsPrec :: Int -> MatchType -> ShowS
  show :: MatchType -> String
  showList :: [MatchType] -> ShowS

instance Eq MatchType where
  (==) :: MatchType -> MatchType -> Bool
  (/=) :: MatchType -> MatchType -> Bool

instance Ord MatchType where
  compare :: MatchType -> MatchType -> Ordering
  (<) :: MatchType -> MatchType -> Bool
  (<=) :: MatchType -> MatchType -> Bool
  (>) :: MatchType -> MatchType -> Bool
  (>=) :: MatchType -> MatchType -> Bool
  max :: MatchType -> MatchType -> MatchType
  min :: MatchType -> MatchType -> MatchType

```

--------------------------------

### Criterion Monad Type Definition and Core Functions

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Monad

Defines the Criterion monad, the execution environment for criterion code. It also provides the `withConfig` function to run a Criterion action with a specific configuration and `getGen` to obtain a random number generator.

```haskell
data Criterion a

withConfig :: Config -> Criterion a -> IO a
getGen :: Criterion GenIO
```

--------------------------------

### OutlierEffect: Eq and Ord Instances

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Analysis

Provides instances for equality (`Eq`) and ordering (`Ord`) for the `OutlierEffect` data type. These instances allow `OutlierEffect` values to be compared for equality and sorted, enabling their use in data structures that require ordering.

```haskell
instance Eq OutlierEffect where
  (==) :: OutlierEffect -> OutlierEffect -> Bool
  (/=) :: OutlierEffect -> OutlierEffect -> Bool

instance Ord OutlierEffect where
  compare :: OutlierEffect -> OutlierEffect -> Ordering
  (<) :: OutlierEffect -> OutlierEffect -> Bool
  (<=) :: OutlierEffect -> OutlierEffect -> Bool
  (>) :: OutlierEffect -> OutlierEffect -> Bool
  (>=) :: OutlierEffect -> OutlierEffect -> Bool
  max :: OutlierEffect -> OutlierEffect -> OutlierEffect
  min :: OutlierEffect -> OutlierEffect -> OutlierEffect
```

--------------------------------

### OutlierEffect: Read and Show Instances

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Analysis

Defines the `Read` and `Show` instances for `OutlierEffect`, allowing it to be parsed from strings and converted into string representations. This is useful for debugging, logging, and interactive use in GHCi.

```haskell
instance Read OutlierEffect where
  readsPrec :: Int -> ReadS OutlierEffect

instance Show OutlierEffect where
  show :: OutlierEffect -> String
  showList :: [OutlierEffect] -> ShowS
```

--------------------------------

### Read Instance for Config in Criterion

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Types

The Read instance for Config allows parsing String representations back into Config values. It defines functions like readsPrec and readListPrec to handle the conversion, enabling configuration to be read from text-based sources. This is crucial for loading configurations from files or command-line arguments.

```haskell
readsPrec :: Int -> ReadS Config
readList :: ReadS [Config]
readPrec :: ReadPrec Config
readListPrec :: ReadPrec [Config]
```

--------------------------------

### whnfAppIO - Weak Head Normal Form Applied IO Evaluation

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main

Apply an argument to a function which performs an IO action, then evaluate the result to weak head normal form (WHNF). Constructs the IO value on each iteration.

```APIDOC
## whnfAppIO

### Description
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 whnf.

### Signature
```haskell
whnfAppIO :: (a -> IO b) -> a -> Benchmarkable
```

### Parameters
- **function** (a -> IO b) - Required - A function returning an IO action
- **argument** (a) - Required - The argument to apply to the function

### Returns
- **Benchmarkable** - A benchmark that can be executed

### Notes
Particularly useful for IO 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.
```

--------------------------------

### Benchmark IO Action to Weak Head Normal Form - Haskell

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

The whnfIO function benchmarks an IO action by evaluating its result to weak head normal form. It takes an IO action, producing a Benchmarkable for measuring IO performance without full evaluation.

```haskell
whnfIO :: IO a -> Benchmarkable
```

--------------------------------

### Defining Individual Benchmarks in Haskell

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/package/criterion

Shows how to define an individual benchmark using the 'bench' function in Criterion. This function takes a benchmark name (String) and a Benchmarkable entity as arguments. It is the core function for specifying what code to benchmark.

```haskell
bench :: String -> Benchmarkable -> Benchmark
bench = Benchmark


```

--------------------------------

### Haskell: Benchmark pure function to weak head normal form (WHNF) with Criterion

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/package/criterion

This Haskell snippet shows how to benchmark a pure function using `whnf` from the Criterion library. `whnf` evaluates the result of the function only to weak head normal form (WHNF). This is suitable for simple return types like `Int` where further evaluation is not complex or costly.

```haskell
main = defaultMain [
  bgroup "fib" [ bench "1"  $ whnf fib 1
               , bench "5"  $ whnf fib 5
               , bench "9"  $ whnf fib 9
               , bench "11" $ whnf fib 11
               ]
  ]

```

--------------------------------

### Loading Mustache Templates

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Report

Provides functions for loading Mustache template files. `loadTemplate` searches for a template by name or path, potentially using embedded data files. `includeFile` attempts to include the content of another file within a template, using a specified search path.

```haskell
loadTemplate :: [FilePath] -> FilePath -> IO Text
-- Throws TemplateException if not found or IOException if loading fails.
```

```haskell
includeFile :: MonadIO m => [FilePath] -> FilePath -> m Text
-- Returns empty if search fails or file cannot be read. Intended for preprocessing.
```

--------------------------------

### Convert IO Action to Benchmarkable - Haskell Criterion

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

The toBenchmarkable function converts a raw IO action into a Benchmarkable. It takes an IO action that receives the number of iterations as an Int64 parameter and produces a Benchmarkable for performance measurement.

```haskell
toBenchmarkable :: (Int64 -> IO ()) -> Benchmarkable
```

--------------------------------

### Benchmark Pure Code with Criterion

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main

Benchmark pure functions using `nf` to fully evaluate results to normal form (NF) or `whnf` to evaluate to weak head normal form. Both functions require the function and its last argument to be supplied separately to mitigate GHC's optimizations.

```haskell
nf :: NFData b => (a -> b) -> a -> Benchmarkable
whnf :: (a -> b) -> a -> Benchmarkable
```

--------------------------------

### Benchmark IO Function to Normal Form - Haskell Criterion

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

The nfAppIO function benchmarks an IO-returning function by evaluating its result to normal form. It takes a function that returns an IO action and its argument, producing a Benchmarkable for IO function performance measurement.

```haskell
nfAppIO :: NFData b => (a -> IO b) -> a -> Benchmarkable
```

--------------------------------

### perRunEnvWithCleanup - Per-Run Environment with Cleanup

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Types

Creates a Benchmarkable where a fresh environment is allocated for every run with an additional cleanup callback. Provides exception-safe resource cleanup after each benchmark run.

```APIDOC
## perRunEnvWithCleanup

### Description
Create a Benchmarkable where a fresh environment is allocated for every run of the operation to benchmark, with an additional callback to clean up the environment. Resource cleanup is exception safe and runs even if the benchmark throws an exception.

### Signature
```haskell
perRunEnvWithCleanup :: (NFData env, NFData b)
  => IO env
  -> (env -> IO ())
  -> (env -> IO b)
  -> Benchmarkable
```

### Parameters

#### Arguments
- **envSetup** (IO env) - Required - Action that creates the environment for a single run.
- **envCleanup** (env -> IO ()) - Required - Clean up the created environment after each run.
- **benchmarkFn** (env -> IO b) - Required - Function returning the IO action that should be benchmarked with the newly generated environment.

### Use Cases
- Benchmarking mutable operations with guaranteed resource cleanup
- Operations requiring exception-safe resource deallocation
- Scenarios where per-run allocation with cleanup is necessary

### Notes
- Similar to `perRunEnv` but includes cleanup callback
- Cleanup runs even if benchmark throws exception
- Environment is evaluated to normal form before each run
```

--------------------------------

### Run Benchmark and Return Report - Haskell Criterion

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion

The benchmark' function runs a Benchmarkable and returns a detailed Report instead of printing results. It takes a Benchmarkable and returns an IO action yielding a Report for programmatic analysis.

```haskell
benchmark' :: Benchmarkable -> IO Report
```

--------------------------------

### Haskell: Benchmark lazy IO with Criterion

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/package/criterion

This snippet demonstrates a common pitfall when benchmarking IO actions in Haskell using Criterion. The `readFile` function exhibits lazy I/O, which can lead to resource exhaustion (e.g., 'Too many open files') because file handles are not closed until the entire file content is consumed. This benchmark will likely crash.

```haskell
import Criterion.Main

main = defaultMain [
    bench "whnfIO readFile" $ whnfIO (readFile "BadReadFile.hs")
  ]

```

--------------------------------

### Criterion MatchType Data Type

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Main-Options

Defines the 'MatchType' data type used to specify how benchmark names should be matched. It includes constructors for prefix matching, glob pattern matching, and substring matching (case-sensitive and insensitive).

```haskell
data MatchType
  = Prefix String
  | Glob FilePath
  | Pattern String
  | IPattern String
```

--------------------------------

### Include File Content - Haskell

Source: https://hackage.haskell.org/package/criterion-1.6.4.1/docs/Criterion-Report

Includes file content from a list of search paths in a monadic context. This function supports any MonadIO instance and retrieves file content as Text, useful for embedding resources within Criterion reports.

```haskell
includeFile :: MonadIO m => [FilePath] -> FilePath -> m Text
```
Tokens:
Raw