weigh-0.0.7: 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.

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)

Synopsis

- mainWith :: Weigh a -> IO ()
- weighResults :: Weigh a -> IO ([(Weight, Maybe String)], Config)
- setColumns :: [Column] -> Weigh ()
- data Column
  - = Case
  - | Allocated
  - | GCs
  - | Live
  - | Check
  - | Max
- func :: NFData a => 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 ()
- validateAction :: NFData a => String -> (b -> IO a) -> b -> (Weight -> Maybe String) -> Weigh ()
- validateFunc :: NFData a => String -> (b -> a) -> b -> (Weight -> Maybe String) -> Weigh ()
- maxAllocs :: Int64 -> Weight -> Maybe String
- data Weigh a
- data Weight = Weight {
  - weightLabel :: !String
  - weightAllocatedBytes :: !Int64
  - weightGCs :: !Int64
  - weightLiveBytes :: !Int64
  - weightMaxBytes :: !Int64
  }
- commas :: (Num a, Integral a, Show a) => a -> String
- weighDispatch :: [String] -> [(String, Action)] -> IO (Maybe [Weight])
- weighFunc :: NFData a => (b -> a) -> b -> IO (Int64, Int64, Int64, Int64)
- weighAction :: NFData a => (b -> IO a) -> b -> IO (Int64, Int64, Int64, Int64)

# Main entry points

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

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

weighResults :: Weigh a -> IO ([(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 config. Default is: `defaultConfig`.

data Column Source #

Table column.

Constructors

Case |
Allocated |
GCs |
Live |
Check |
Max |

Instances

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

# 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`.

io Source #

Arguments

:: NFData a |
=> String | Name of the case.
-> (b -> IO a) | Aciton 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`.

# 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

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

Make a validator that set sthe maximum allocations.

# Types

data Weigh a Source #

Weigh specification monad.

Instances

Monad Weigh Source # |
Methods (>>=) :: Weigh a -> (a -> Weigh b) -> Weigh b # (>>) :: Weigh a -> Weigh b -> Weigh b # return :: a -> Weigh a # fail :: String -> Weigh a #
Functor Weigh Source # |
Methods fmap :: (a -> b) -> Weigh a -> Weigh b # (<$) :: a -> Weigh b -> Weigh a #
Applicative Weigh Source # |
Methods pure :: a -> Weigh a # (<*>) :: Weigh (a -> b) -> Weigh a -> Weigh b # (*>) :: Weigh a -> Weigh b -> Weigh b # (<*) :: Weigh a -> Weigh b -> Weigh a #

data Weight Source #

How much a computation weighed in at.

Constructors

Weight |

Fields

- weightLabel :: !String
- weightAllocatedBytes :: !Int64
- weightGCs :: !Int64
- weightLiveBytes :: !Int64
- weightMaxBytes :: !Int64

Instances

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

# Handy utilities

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

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

# Internals

weighDispatch Source #

Arguments

:: [String] | Program arguments.
-> [(String, Action)] | Weigh name:action mapping.
-> IO (Maybe [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 (Int64, Int64, Int64, Int64) | Bytes allocated and garbage collections.

Weigh a pure function. 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 (Int64, Int64, Int64, Int64) | Bytes allocated and garbage collections.

Weigh a pure function. This function is heavily documented inside.