Bodigrim/tasty-bench
1
1
Fork 0
mirror of https://github.com/Bodigrim/tasty-bench.git synced 2024-09-11 08:45:33 +03:00
Code Issues Projects Releases Wiki Activity

Emphasize difference between nf and whnf . rnf

Browse Source
This commit is contained in:
Bodigrim 2023-02-11 20:44:46 +00:00
parent 9c8699014b
commit 461919e581
1 changed files with 12 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
src/Test/Tasty/Bench.hs
View File

@ -1245,7 +1245,8 @@ funcToBench frc = (Benchmarkable .) . benchLoop SPEC
{-# INLINE funcToBench #-}
-- | 'nf' @f@ @x@ measures time to compute
-- a normal form (by means of 'force') of an application of @f@ to @x@.
-- a normal form (by means of 'force', not 'Control.DeepSeq.rnf')
-- of an application of @f@ to @x@.
-- This does not include time to evaluate @f@ or @x@ themselves.
-- Ideally @x@ should be a primitive data type like 'Data.Int.Int'.
--
@ -1272,11 +1273,16 @@ funcToBench frc = (Benchmarkable .) . benchLoop SPEC
-- such measurements are noisy and involve an overhead. Results are more reliable
-- when @f@ @x@ takes at least several milliseconds.
--
-- Note that forcing a normal form requires an additional
-- Remember that forcing a normal form requires an additional
-- traverse of the structure. In certain scenarios (imagine benchmarking 'tail'),
-- especially when 'NFData' instance is badly written,
-- this traversal may take non-negligible time and affect results.
--
-- 'nf' @f@ is equivalent to 'whnf' ('force' '.' @f@), but not to
-- 'whnf' ('Control.DeepSeq.rnf' '.' @f@). The former retains the result
-- in memory until it is fully evaluated, while the latter allows
-- evaluated parts of the result to be garbage-collected immediately.
--
-- Drop-in replacement for @Criterion.@'Criterion.nf' and
-- @Gauge.@'Gauge.nf'.
--
@ -1327,14 +1333,14 @@ ioToBench frc act = Benchmarkable go
{-# INLINE ioToBench #-}
-- | 'nfIO' @x@ measures time to evaluate side-effects of @x@
-- and compute its normal form (by means of 'force').
-- and compute its normal form (by means of 'force', not 'Control.DeepSeq.rnf').
--
-- Pure subexpression of an effectful computation @x@
-- may be evaluated only once and get cached.
-- To avoid surprising results it is usually preferable
-- to use 'nfAppIO' instead.
--
-- Note that forcing a normal form requires an additional
-- Remember that forcing a normal form requires an additional
-- traverse of the structure. In certain scenarios,
-- especially when 'NFData' instance is badly written,
-- this traversal may take non-negligible time and affect results.
@ -1389,7 +1395,7 @@ ioFuncToBench frc = (Benchmarkable .) . go
-- | 'nfAppIO' @f@ @x@ measures time to evaluate side-effects of
-- an application of @f@ to @x@
-- and compute its normal form (by means of 'force').
-- and compute its normal form (by means of 'force', not 'Control.DeepSeq.rnf').
-- This does not include time to evaluate @f@ or @x@ themselves.
-- Ideally @x@ should be a primitive data type like 'Data.Int.Int'.
--
@ -1400,7 +1406,7 @@ ioFuncToBench frc = (Benchmarkable .) . go
-- but if @x@ is not a primitive data type, consider forcing its evaluation
-- separately, e. g., via 'env' or 'withResource'.
--
-- Note that forcing a normal form requires an additional
-- Remember that forcing a normal form requires an additional
-- traverse of the structure. In certain scenarios,
-- especially when 'NFData' instance is badly written,
-- this traversal may take non-negligible time and affect results.