weigh-0.0.18: Measure allocations of a Haskell functions/values

Safe Haskell | None
Language | Haskell2010

Weigh

Contents

- Main entry points
- Configuration
- Simple combinators
- Validating combinators
- Validators
- Types
- Handy utilities
- Internals

Description

Framework for seeing how much a function allocates.

WARNING: weigh is incompatible with profiling. It reports much more allocations with profiling turned on.

Example:

    import Weigh
    main =
      mainWith (do func "integers count 0" count 0
                   func "integers count 1" count 1
                   func "integers count 2" count 2
                   func "integers count 3" count 3
                   func "integers count 10" count 10
                   func "integers count 100" count 100)
      where count :: Integer -> ()
            count 0 = ()
            count a = count (a - 1)

Use `wgroup` to group sets of tests.

Synopsis

- mainWith :: Weigh a -> IO ()
- weighResults :: Weigh a -> IO ([Grouped (Weight, Maybe String)], Config)
- setColumns :: [Column] -> Weigh ()
- data Column
  - = Case
  - | Allocated
  - | GCs
  - | Live
  - | Check
  - | Max
  - | MaxOS
  - | WallTime
- setFormat :: Format -> Weigh ()
- data Format
  - = Plain
  - | Markdown
- setConfig :: Config -> Weigh ()
- data Config = Config {
  - configColumns :: [Column]
  - configPrefix :: String
  - configFormat :: !Format
  }
- defaultConfig :: Config
- func :: NFData a => String -> (b -> a) -> b -> Weigh ()
- func' :: (NFData a, NFData b) => String -> (b -> a) -> b -> Weigh ()
- io :: NFData a => String -> (b -> IO a) -> b -> Weigh ()
- value :: NFData a => String -> a -> Weigh ()
- action :: NFData a => String -> IO a -> Weigh ()
- wgroup :: String -> Weigh () -> Weigh ()
- validateAction :: NFData a => String -> (b -> IO a) -> b -> (Weight -> Maybe String) -> Weigh ()
- validateFunc :: NFData a => String -> (b -> a) -> b -> (Weight -> Maybe String) -> Weigh ()
- maxAllocs :: Word64 -> Weight -> Maybe String
- data Weigh a
- data Weight = Weight {
  - weightLabel :: !String
  - weightAllocatedBytes :: !Word64
  - weightGCs :: !Word32
  - weightLiveBytes :: !Word64
  - weightMaxBytes :: !Word64
  - weightMaxOSBytes :: !Word64
  - weightWallTime :: !Double
  }
- commas :: (Num a, Integral a, Show a) => a -> String
- reportGroup :: Config -> [Char] -> [Grouped (Weight, Maybe String)] -> [Char]
- weighDispatch :: Maybe String -> [Grouped Action] -> IO (Maybe [Grouped Weight])
- weighFunc :: NFData a => (b -> a) -> b -> IO (Word64, Word32, Word64, Word64, Word64)
- weighFuncResult :: NFData a => (b -> a) -> b -> IO (a, (Word64, Word32, Word64, Word64, Word64))
- weighAction :: NFData a => (b -> IO a) -> b -> IO (Word64, Word32, Word64, Word64, Word64)
- weighActionResult :: NFData a => (b -> IO a) -> b -> IO (a, (Word64, Word32, Word64, Word64, Word64))
- data Grouped a
  - = Grouped String [Grouped a]
  - | Singleton a

# Main entry points

mainWith :: Weigh a -> IO () Source #

Just run the measuring and print a report. Uses `weighResults`.

weighResults :: Weigh a -> IO ([Grouped (Weight, Maybe String)], Config) Source #

Run the measuring and return all the results, each one may have an error.

# Configuration

setColumns :: [Column] -> Weigh () Source #

Set the columns to display in the config

data Column Source #

Table column.

Constructors

Case | Case name for the column
Allocated | Total bytes allocated
GCs | Total number of GCs
Live | Total amount of live data in the heap
Check | Table column indicating about the test status
Max | Maximum residency memory in use
MaxOS | Maximum memory in use by the RTS. Valid only for GHC >= 8.2.2. For unsupported GHC, this is reported as 0.
WallTime | Rough execution time. For general indication, not a benchmark tool.

#### Instances

Instances details

Enum Column Source # |
Instance details Defined in Weigh Methods succ :: Column -> Column Source # pred :: Column -> Column Source # toEnum :: Int -> Column Source # fromEnum :: Column -> Int Source # enumFrom :: Column -> [Column] Source # enumFromThen :: Column -> Column -> [Column] Source # enumFromTo :: Column -> Column -> [Column] Source # enumFromThenTo :: Column -> Column -> Column -> [Column] Source #
Show Column Source # |
Instance details Defined in Weigh Methods showsPrec :: Int -> Column -> ShowS Source # show :: Column -> String Source # showList :: [Column] -> ShowS Source #
Eq Column Source # |
Instance details Defined in Weigh Methods (==) :: Column -> Column -> Bool Source # (/=) :: Column -> Column -> Bool Source #

setFormat :: Format -> Weigh () Source #

Set the output format in the config

data Format Source #

Constructors

Plain |
Markdown |

#### Instances

Instances details

Show Format Source # |
Instance details Defined in Weigh Methods showsPrec :: Int -> Format -> ShowS Source # show :: Format -> String Source # showList :: [Format] -> ShowS Source #

setConfig :: Config -> Weigh () Source #

Set the config. Default is: `defaultConfig`.

data Config Source #

Weigh configuration.

Constructors

Config |

Fields

- configColumns :: [Column]
- configPrefix :: String
- configFormat :: !Format

#### Instances

Instances details

Show Config Source # |
Instance details Defined in Weigh Methods showsPrec :: Int -> Config -> ShowS Source # show :: Config -> String Source # showList :: [Config] -> ShowS Source #

defaultConfig :: Config Source #

Default config.

# Simple combinators

func Source #

Arguments

:: NFData a |
=> String | Name of the case.
-> (b -> a) | Function that does some action to measure.
-> b | Argument to that function.
-> Weigh () |

Weigh a function applied to an argument.

Implemented in terms of `validateFunc`.

func' :: (NFData a, NFData b) => String -> (b -> a) -> b -> Weigh () Source #

Weigh a function applied to an argument. Unlike `func`, the argument is evaluated to normal form before the function is applied.

io Source #

Arguments

:: NFData a |
=> String | Name of the case.
-> (b -> IO a) | Action that does some IO to measure.
-> b | Argument to that function.
-> Weigh () |

Weigh an action applied to an argument.

Implemented in terms of `validateAction`.

value Source #

Arguments

:: NFData a |
=> String | Name for the value.
-> a | The value to measure.
-> Weigh () |

Weigh a value.

Implemented in terms of `action`.

action Source #

Arguments

:: NFData a |
=> String | Name for the value.
-> IO a | The action to measure.
-> Weigh () |

Weigh an IO action.

Implemented in terms of `validateAction`.

wgroup :: String -> Weigh () -> Weigh () Source #

Make a grouping of tests.

# Validating combinators

validateAction Source #

Arguments

:: NFData a |
=> String | Name of the action.
-> (b -> IO a) | The function which performs some IO.
-> b | Argument to the function. Doesn't have to be forced.
-> (Weight -> Maybe String) | A validating function, returns maybe an error.
-> Weigh () |

Weigh an IO action, validating the result.

validateFunc Source #

Arguments

:: NFData a |
=> String | Name of the function.
-> (b -> a) | The function which calculates something.
-> b | Argument to the function. Doesn't have to be forced.
-> (Weight -> Maybe String) | A validating function, returns maybe an error.
-> Weigh () |

Weigh a function, validating the result

# Validators

maxAllocs Source #

Arguments

:: Word64 | The upper bound.
-> Weight |
-> Maybe String |

Make a validator that set sthe maximum allocations.

# Types

data Weigh a Source #

Weigh specification monad.

#### Instances

Instances details

Applicative Weigh Source # |
Instance details Defined in Weigh Methods pure :: a -> Weigh a Source # (<*>) :: Weigh (a -> b) -> Weigh a -> Weigh b Source # liftA2 :: (a -> b -> c) -> Weigh a -> Weigh b -> Weigh c Source # (*>) :: Weigh a -> Weigh b -> Weigh b Source # (<*) :: Weigh a -> Weigh b -> Weigh a Source #
Functor Weigh Source # |
Instance details Defined in Weigh Methods fmap :: (a -> b) -> Weigh a -> Weigh b Source # (<$) :: a -> Weigh b -> Weigh a Source #
Monad Weigh Source # |
Instance details Defined in Weigh Methods (>>=) :: Weigh a -> (a -> Weigh b) -> Weigh b Source # (>>) :: Weigh a -> Weigh b -> Weigh b Source # return :: a -> Weigh a Source #

data Weight Source #

How much a computation weighed in at.

Constructors

Weight |

Fields

- weightLabel :: !String
- weightAllocatedBytes :: !Word64
- weightGCs :: !Word32
- weightLiveBytes :: !Word64
- weightMaxBytes :: !Word64
- weightMaxOSBytes :: !Word64
- weightWallTime :: !Double

#### Instances

Instances details

Read Weight Source # |
Instance details Defined in Weigh Methods readsPrec :: Int -> ReadS Weight Source # readList :: ReadS [Weight] Source # readPrec :: ReadPrec Weight Source # readListPrec :: ReadPrec [Weight] Source #
Show Weight Source # |
Instance details Defined in Weigh Methods showsPrec :: Int -> Weight -> ShowS Source # show :: Weight -> String Source # showList :: [Weight] -> ShowS Source #

# Handy utilities

commas :: (Num a, Integral a, Show a) => a -> String Source #

Formatting an integral number to 1,000,000, etc.

reportGroup :: Config -> [Char] -> [Grouped (Weight, Maybe String)] -> [Char] Source #

# Internals

weighDispatch Source #

Arguments

:: Maybe String | The content of then env variable WEIGH_CASE.
-> [Grouped Action] | Weigh name:action mapping.
-> IO (Maybe [Grouped Weight]) |

Weigh a set of actions. The value of the actions are forced completely to ensure they are fully allocated.

weighFunc Source #

Arguments

:: NFData a |
=> (b -> a) | A function whose memory use we want to measure.
-> b | Argument to the function. Doesn't have to be forced.
-> IO (Word64, Word32, Word64, Word64, Word64) | Bytes allocated and garbage collections.

Weigh a pure function. This function is built on top of `weighFuncResult`, which is heavily documented inside

weighFuncResult Source #

Arguments

:: NFData a |
=> (b -> a) | A function whose memory use we want to measure.
-> b | Argument to the function. Doesn't have to be forced.
-> IO (a, (Word64, Word32, Word64, Word64, Word64)) | Result, Bytes allocated, GCs.

Weigh a pure function and return the result. This function is heavily documented inside.

weighAction Source #

Arguments

:: NFData a |
=> (b -> IO a) | A function whose memory use we want to measure.
-> b | Argument to the function. Doesn't have to be forced.
-> IO (Word64, Word32, Word64, Word64, Word64) | Bytes allocated and garbage collections.

Weigh an IO action. This function is based on `weighActionResult`, which is heavily documented inside.

weighActionResult Source #

Arguments

:: NFData a |
=> (b -> IO a) | A function whose memory use we want to measure.
-> b | Argument to the function. Doesn't have to be forced.
-> IO (a, (Word64, Word32, Word64, Word64, Word64)) | Result, Bytes allocated and GCs.

Weigh an IO action, and return the result. This function is heavily documented inside.

data Grouped a Source #

Some grouped thing.

Constructors

Grouped String [Grouped a] |
Singleton a |

#### Instances

Instances details

Functor Grouped Source # |
Instance details Defined in Weigh Methods fmap :: (a -> b) -> Grouped a -> Grouped b Source # (<$) :: a -> Grouped b -> Grouped a Source #
Foldable Grouped Source # |

Instance details

Defined in Weigh

Methods

fold :: Monoid m => Grouped m -> m Source #

foldMap :: Monoid m => (a -> m) -> Grouped a -> m Source #

foldMap' :: Monoid m => (a -> m) -> Grouped a -> m Source #

foldr :: (a -> b -> b) -> b -> Grouped a -> b Source #

foldr' :: (a -> b -> b) -> b -> Grouped a -> b Source #

foldl :: (b -> a -> b) -> b -> Grouped a -> b Source #

foldl' :: (b -> a -> b) -> b -> Grouped a -> b Source #

foldr1 :: (a -> a -> a) -> Grouped a -> a Source #

foldl1 :: (a -> a -> a) -> Grouped a -> a Source #

toList :: Grouped a -> [a] Source #

null :: Grouped a -> Bool Source #

length :: Grouped a -> Int Source #

elem :: Eq a => a -> Grouped a -> Bool Source #

maximum :: Ord a => Grouped a -> a Source #

minimum :: Ord a => Grouped a -> a Source #

sum :: Num a => Grouped a -> a Source #

product :: Num a => Grouped a -> a Source #

Traversable Grouped Source # |
Instance details Defined in Weigh Methods traverse :: Applicative f => (a -> f b) -> Grouped a -> f (Grouped b) Source # sequenceA :: Applicative f => Grouped (f a) -> f (Grouped a) Source # mapM :: Monad m => (a -> m b) -> Grouped a -> m (Grouped b) Source # sequence :: Monad m => Grouped (m a) -> m (Grouped a) Source #
NFData a => NFData (Grouped a) Source # |
Instance details Defined in Weigh Methods rnf :: Grouped a -> () Source #
Generic (Grouped a) Source # |

Instance details

Defined in Weigh

Associated Types

type Rep (Grouped a) |

Instance details

Defined in Weigh

type Rep (Grouped a) = D1 ('MetaData "Grouped" "Weigh" "weigh-0.0.18-5YE7sjN1HiEDJZotPKAbRW" 'False) (C1 ('MetaCons "Grouped" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Grouped a])) :+: C1 ('MetaCons "Singleton" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)))

Methods

from :: Grouped a -> Rep (Grouped a) x Source #

to :: Rep (Grouped a) x -> Grouped a Source #

Show a => Show (Grouped a) Source # |
Instance details Defined in Weigh Methods showsPrec :: Int -> Grouped a -> ShowS Source # show :: Grouped a -> String Source # showList :: [Grouped a] -> ShowS Source #
Eq a => Eq (Grouped a) Source # |
Instance details Defined in Weigh Methods (==) :: Grouped a -> Grouped a -> Bool Source # (/=) :: Grouped a -> Grouped a -> Bool Source #
type Rep (Grouped a) Source # |

Instance details

Defined in Weigh

type Rep (Grouped a) = D1 ('MetaData "Grouped" "Weigh" "weigh-0.0.18-5YE7sjN1HiEDJZotPKAbRW" 'False) (C1 ('MetaCons "Grouped" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Grouped a])) :+: C1 ('MetaCons "Singleton" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)))