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


-- | A benchmark suite for runtime and heap measurements over
a series of inputs.
--   
--   The package provides a framework for heap and runtime measurements for
--   single Haskell functions. For heap measurements simple programs are
--   created, compiled with profiling options and run. You can do either a
--   heap profile or a graph for the maximal heap consumption of a function
--   over different inputsizes. For runtime measurements the criterion
--   library is used. Measurement data can be stored in a special file
--   format providing besides the data some meta information about the
--   measurement. Furthermore measured data can be plotted easily using
--   gnuplot. In particular, it is possible to compare measurements for
--   different functions (e.g. different version of a semantically
--   equivalent function) in one diagram. By using gnuplot for drawing, the
--   appearance of a diagram is very flexible and can be adjusted directly
--   to, for example, the style of your paper.
@package SBench
@version 0.2.0

module Test.SBench.Space.Single.ExploreProfile
getMaxMem :: FilePath -> IO Integer
getMemLine :: FilePath -> IO [(Double, Integer)]

module Test.SBench.Options

-- | The possible types of parameters.
data ProfParam :: *

-- | The type of breakdown.
PPBreakdown :: Breakdown -> ProfParam

-- | An additional filter on the runtime side.
PPRestriction :: Restriction -> [String] -> ProfParam

-- | Sampling interval in seconds.
PPInterval :: Float -> ProfParam

-- | Whether to include memory taken up by threads.
PPIncludeThreads :: ProfParam

-- | The maximum length of cost centre stack names.
PPNameLength :: Int -> ProfParam

-- | Retainer set size limit.
PPRetainerLimit :: Int -> ProfParam

-- | The possible types of breakdowns.
data Breakdown :: *

-- | Breakdown by cost centre stack (origin of the data).
BCostCentreStack :: Breakdown

-- | Breakdown by module (code responsible for the data).
BModule :: Breakdown

-- | Breakdown by closure description (constructor name or some unique
--   identifier).
BDescription :: Breakdown

-- | Breakdown by type (or an approximation if it is not known exactly).
BType :: Breakdown

-- | Breakdown by retainer set (effectively the entities that hold a direct
--   reference to the data in question).
BRetainer :: Breakdown

-- | Breakdown by biography (phase of an object's lifetime).
BBiography :: Breakdown

-- | The possible filters. Note that these are imposed by the runtime, so
--   we cannot override them on the application side.
data Restriction :: *

-- | Show only closures with one of the given names on the top of the cost
--   centre stack.
RCCStackTop :: Restriction

-- | Show only closures with one of the given names somewhere in the cost
--   centre stack.
RCCStackAny :: Restriction

-- | Show only closures produced by one of the given modules.
RModule :: Restriction

-- | Show only closures with a description that matches one of the given
--   names.
RDescription :: Restriction

-- | Show only closures with one of the given types.
RType :: Restriction

-- | Show only closures with retainer sets that contain at least one cost
--   centre stack with a given name on the top.
RRetainer :: Restriction

-- | Show only closures with one of the specified biographies, which must
--   come from the set {lag, drag, void, use}.
RBiography :: Restriction
type Imports = [String]
type CompilerOptions = [String]
type ProgramArguments = [String]
type MemoryOptions = [MemSize]
type ProfilingOptions = [ProfParam]
type Repetitions = Int
type ThreadNum = Int
data MemUnit
G :: MemUnit
M :: MemUnit
K :: MemUnit
B :: MemUnit
data MemSize
Heap :: Int -> MemUnit -> MemSize
Stack :: Int -> MemUnit -> MemSize
data TestOpts
TOpts :: CompilerOptions -> RuntimeOptions -> Maybe Repetitions -> NormalInput -> TestOpts
cOpts :: TestOpts -> CompilerOptions
rOpts :: TestOpts -> RuntimeOptions
reps :: TestOpts -> Maybe Repetitions
nfInp :: TestOpts -> NormalInput
data RuntimeOptions
ROpts :: Maybe ThreadNum -> ProfilingOptions -> MemoryOptions -> ProgramArguments -> RuntimeOptions
threadNum :: RuntimeOptions -> Maybe ThreadNum
profOpts :: RuntimeOptions -> ProfilingOptions
memOpts :: RuntimeOptions -> MemoryOptions
progArgs :: RuntimeOptions -> ProgramArguments
data EvalMod
NF :: EvalMod
WHNF :: EvalMod
type NormalInput = Bool
opts2string :: [String] -> String
type Title = String
instance Show EvalMod
instance Show MemUnit
instance Show MemSize
instance Show RuntimeOptions

module Test.SBench.File.Types

-- | Metainformation stored in the header of all .sbench files. Part of the
--   <a>MetaInfo</a> entries are usually calculated automatically.
data (Real a, Real b) => MetaInfo a b
MetaInfo :: [String] -> String -> String -> String -> Either String String -> Maybe EvalMod -> (Range a, Range b) -> String -> String -> MetaInfo a b
header :: MetaInfo a b -> [String]
sbenchVersion :: MetaInfo a b -> String
miGraphTitle :: MetaInfo a b -> String
miAlgName :: MetaInfo a b -> String
miGenName :: MetaInfo a b -> Either String String

-- | <a>Left</a> means an input generator, <a>Right</a> a single input
evalMod :: MetaInfo a b -> Maybe EvalMod
graphRanges :: MetaInfo a b -> (Range a, Range b)
buildOptions :: MetaInfo a b -> String
exeOptions :: MetaInfo a b -> String
data Real a => Range a
AutoRange :: Range a
ManRange :: (a, a) -> Range a
instance (Show a, Real a, Show b, Real b) => Show (MetaInfo a b)


-- | The provided data type <a>STerm</a> is intended to store a term
--   equipped with its own name and maybe some extra information about its
--   cost center annotation and modules that need to be loaded when
--   evaluating the term.
--   
--   The additional information, provided as strings, is necessary for
--   space measurements where small programs are constructed from the
--   strings and run for heap profiling.
module Test.SBench.STerm
type CostCenter = String
type DataGen a = STerm a
type Algorithm a = STerm a
type Data a = STerm a
type Seed a = STerm a
type Test a b = Data a -> FilePath -> IO b
data STerm a
T :: a -> TermName -> [ModuleName] -> [CostCenter] -> STerm a

-- | The actual term.
stTerm :: STerm a -> a

-- | The term as <a>String</a>
stName :: STerm a -> TermName

-- | The modules used when evaluation the term
stModules :: STerm a -> [ModuleName]

-- | cost centers to measure when performing heap profiling.
stCC :: STerm a -> [CostCenter]
toData :: Show a => a -> STerm a
toNamedData :: Show a => a -> TermName -> STerm a
toDataGen :: (a -> b) -> ModuleName -> TermName -> Data (a -> b)
toAlgorithm :: (a -> b) -> ModuleName -> TermName -> CostCenter -> Algorithm (a -> b)

-- | Function application for <a>STerm</a>.
(<$>) :: STerm (a -> b) -> STerm a -> STerm b
getImports :: STerm a -> String
makeSeeds :: (Show a, Integral a) => a -> a -> a -> [Seed a]

-- | Auxiliar version of <a>makeSeeds</a> to prevent defaulting to
--   <a>Integer</a>.
makeIntSeeds :: Int -> Int -> Int -> [Seed Int]
instance Show (STerm a)

module Test.SBench.File.FileOps

-- | Read the mean runtimes of a criterion data file and tuple them with
--   seeds to a seed-runtime series.
criterion2series :: Num a => [a] -> CriterionFile -> IO [(a, Double)]

-- | Store a series of measurements over <i>different inputs</i> in a
--   .sbench file. The SBench file format take some extra information about
--   the measurement.
series2sbench :: (Show a, Real a, Show b, Real b) => (String, String) -> Maybe EvalMod -> Algorithm (c -> d) -> DataGen (e -> c) -> Title -> SBenchFile -> [(a, b)] -> IO SBenchFile

-- | Store a series of measurements with <i>a single input</i> in a .sbench
--   file. The SBench file format take some extra information about the
--   measurement.
series2sbench' :: (Show a, Real a, Show b, Real b) => (String, String) -> Maybe EvalMod -> Algorithm (c -> d) -> Data c -> Title -> SBenchFile -> [(a, b)] -> IO SBenchFile

-- | Read a measurment series from a .sbench data file. Additionally to the
--   measurement series a data structure with meta informations is
--   returned.
sbench2series :: FilePath -> IO (MetaInfo Double Double, [(Double, Double)])


-- | Interface functions to the <a>gnuplot</a> package for generating
--   plots.
module Test.SBench.Plot.Gnuplot
series2plot :: (C a, C a, C b, C b) => Title -> [(a, b)] -> T a b
series2scaledPlot :: (C c, C c, C d, C d) => (a -> c) -> (b -> d) -> Title -> [(a, b)] -> T c d
series2plotWith :: (C a, C a, C b, C b) => [T -> T] -> [(a, b)] -> T a b
series2scaledPlotWith :: (C c, C c, C d, C d) => [T -> T] -> (a -> c) -> (b -> d) -> [(a, b)] -> T c d
series2plotWithLinestyle :: (C a, C a, C b, C b) => Int -> Title -> [(a, b)] -> T a b
series2scaledPlotWithLinestyle :: (C c, C c, C d, C d) => Int -> (a -> c) -> (b -> d) -> Title -> [(a, b)] -> T c d
sbench2plot :: FilePath -> IO (T Double Double)
sbench2scaledPlot :: (Double -> Double) -> (Double -> Double) -> FilePath -> IO (T Double Double)
sbench2plotWithLinestyle :: Int -> FilePath -> IO (T Double Double)
sbench2scaledPlotWithLinestyle :: Int -> (Double -> Double) -> (Double -> Double) -> FilePath -> IO (T Double Double)
sbench2plotWith :: [T -> T] -> FilePath -> IO (T Double Double)
sbench2scaledPlotWith :: [T -> T] -> (Double -> Double) -> (Double -> Double) -> FilePath -> IO (T Double Double)

-- | Compared to <a>toDiagramWith</a>, the output terminal is fixed to
--   <a>Graphics.Gnuplot.Terminal.PostScript</a> and the resulting .eps
--   file is transformed to a .pdf via a call to <tt>epstopdf</tt>.
--   
--   The parameters are as follows [<tt>name</tt>] Choose the output
--   terminal. See <a>Graphics.Gnuplot.Terminal</a> [<tt>topts</tt>] Frame
--   options, e.g. title. See <a>Graphics.Gnuplot.Frame.OptionSet</a>
--   [<tt>opts</tt>] List of plots to be shown in the diagram.
--   [<tt>plots</tt>] List of plots to be shown in the diagram.
toDiagram :: (C a, C b, C a, C b) => [Char] -> [T -> T] -> [T (T a b) -> T (T a b)] -> [T a b] -> IO FilePath

-- | Produces a diagram with several plots inside.
--   
--   The parameters are as follows [<tt>terminal</tt>] Choose the output
--   terminal. See <a>Graphics.Gnuplot.Terminal</a> [<tt>opts</tt>] Frame
--   options, e.g. title. See <a>Graphics.Gnuplot.Frame.OptionSet</a>
--   [<tt>plots</tt>] List of plots to be shown in the diagram.
toDiagramWith :: (C a, C b, C a, C b, C terminal) => terminal -> [T (T a b) -> T (T a b)] -> [T a b] -> IO ExitCode


-- | Functions for runtime tests are provided. They are basically a wrapper
--   to a call to the criterion function
--   <a>Criterion.Main.defaultMainWith</a>. The measurement data (usually
--   stored in temp.csv) is than postprocessed by extracting only the mean
--   runtime for each run and tupling it with the respective input seed.
--   Results are then returned as list of tuples and optionally stored in a
--   .sbench file (see <a>Test.File.FileOps</a>).
module Test.SBench.Time.Series.Test

-- | As <a>runtimeSeriesWith</a>, but <a>Criterion.Config.Config</a> is set
--   to a default.
runtimeSeries :: (NFData b, Show c, Real c) => EvalMod -> Maybe (BuildOptions, ExeOptions, FilePath, Title) -> Algorithm (a -> b) -> DataGen (c -> a) -> [Seed c] -> IO [(c, Double)]

-- | Most general function to perform runtime measurements for a series of
--   inputs.
runtimeSeriesWith :: (NFData b, Show c, Real c) => Config -> EvalMod -> Maybe (BuildOptions, ExeOptions, FilePath, Title) -> Algorithm (a -> b) -> DataGen (c -> a) -> [Seed c] -> IO [(c, Double)]
nfRuntimeSeries :: (NFData b, Show c, Real c) => Maybe (BuildOptions, ExeOptions, FilePath, Title) -> Algorithm (a -> b) -> DataGen (c -> a) -> [Seed c] -> IO [(c, Double)]
whnfRuntimeSeries :: (NFData b, Show c, Real c) => Maybe (BuildOptions, ExeOptions, FilePath, Title) -> Algorithm (a -> b) -> DataGen (c -> a) -> [Seed c] -> IO [(c, Double)]
scaleRt :: Double -> [(Int, Double)] -> [(Int, Double)]

module Test.SBench.Space.OptionSet

-- | <ul>
--   <li>Compiler options</li>
--   </ul>
--   
--   Options always added when compiling for space profiling.
generalCOpts :: CompilerOptions

-- | default compiler options additional to <a>generalCOpts</a>.
defltCOpts :: CompilerOptions

-- | By default repetitions are calculated automatically
defltRep :: Maybe Repetitions

-- | Default profiling options.
defltProfOpts :: ProfilingOptions

-- | Default test options, i.e. default options for compiling and running a
--   program for space profiling.
defltTestOpts :: TestOpts
addCC :: Algorithm a -> TestOpts -> TestOpts
setRepetitions :: Repetitions -> TestOpts -> TestOpts
autoRepeat :: TestOpts -> TestOpts
setMemSizes :: [MemSize] -> TestOpts -> TestOpts
setNfInput :: Bool -> TestOpts -> TestOpts

module Test.SBench.Space.Single.Test

-- | Create only the heap profile.
getProfile :: TestOpts -> Algorithm (a -> b) -> Data a -> FilePath -> IO FilePath

-- | Get the maximal heap occupied by the algorithm. Since the algorithms
--   comes with a cost center annotation this is used to explore what heap
--   consumption should be measured (here: all heap directly or indirectly
--   used by the given algorithm).
getMaxMem :: NormalInput -> Algorithm (a -> b) -> Data a -> FilePath -> IO Integer

-- | As <a>getMaxMem</a>, but <a>TestOpts</a> can be set by the user.
getMaxMemWith :: TestOpts -> Algorithm (a -> b) -> Data a -> FilePath -> IO Integer

-- | The function generates a heap profile, returns the heapconsumption
--   over time as series and also stores the series as an .sbench file.
getMemLine :: NormalInput -> (FilePath, Title) -> Algorithm (a -> b) -> Data a -> IO [(Double, Integer)]
getMemLineWith :: TestOpts -> (FilePath, Title) -> Algorithm (a -> b) -> Data a -> IO [(Double, Integer)]

module Test.SBench.Space.Series.Test
makeSeries :: (Show c, Real c, Show d, Real d) => (TestOpts -> Algorithm (a -> b) -> Data a -> FilePath -> IO d) -> TestOpts -> (FilePath, Title) -> Algorithm (a -> b) -> DataGen (c -> a) -> [Seed c] -> IO [(c, d)]

-- | The function measures the maximal heap consumption of a given function
--   over a series of different inputs that are produced via an input
--   generator given different seeds.
maxMemSeries :: (Show c, Real c) => NormalInput -> (FilePath, Title) -> Algorithm (a -> b) -> DataGen (c -> a) -> [Seed c] -> IO [(c, Integer)]

-- | The function acts similar to <a>maxMemSeries</a>, but instead of only
--   <a>NormalInput</a>, <a>TestOpts</a> can be set manually via the first
--   parameter.
maxMemSeriesWith :: (Show c, Real c) => TestOpts -> (FilePath, Title) -> Algorithm (a -> b) -> DataGen (c -> a) -> [Seed c] -> IO [(c, Integer)]