Update docs and disable printing of cpu-time

`:GetProcessTimes` has a resolution of `100ns` which is much worse than the resolution of the high-precision clock.

Author: vchuravy

doc/manual.md

@@ -46,17 +46,22 @@ recording the total time `t` it takes to record `n` evaluations, and estimating
 
 ## The difference between real-time and cpu-time
 BenchmarkTools measures both real-time and cpu-time. Real-time is the time that has passed while running your program and cpu-time is the time
-that a processor has spend executing your program. As an example when the operating system deschedules your program, real-time is still passing,
-but cpu-time is paused, this is also the case when your program spends time in the kernel or is blocked waiting. As an example take a program that
+that a processor has spend executing your program. Real-time is often also referred to as wall-time. As an example take a program that
 is doing `sleep(1)`.
 
 ```julia
 julia> @btime sleep(1)
   1.001 s [0.01% CPU, 0.00% GC] (5 allocations: 192 bytes)
 ```
 
-As we can see, when we call sleep our program is not using CPU cycles and thus cpu-time is `0.01%` of our actual runtime. Do to sligh differences
-in accounting cpu-time can sometimes exceed `100%`.
+As we can see, when we call sleep our program is not using CPU cycles and thus cpu-time is `0.01%` of our actual runtime.
+Sometimes cpu-time can exceed `100%`, this is either due to slight differences in accounting or because your process is
+using multiple cpus.
+
+### Windows
+Cpu-time measurments on Windows have a low resolution (in comparision to real-time) and are as such less useful. To avoid confusion
+printing of cpu-time is disabled by default. If you are benchmarking code that runs in the `ms` range you can set the environment variable
+`BT_FORCE_CPUTIME` to enable printing of cpu-time results (Remeber to evict your cached version of BenchmarkTools).
 
 # Benchmarking basics
 

src/timers/timers.jl

@@ -3,6 +3,8 @@
 module Timers
 import Compat
 
+const ACCURATE_CPUTIME = Compat.Sys.iswindows() ? haskey(ENV, "BT_FORCE_CPUTIME") : true
+
 """
     realtime()
 

src/trials.jl

@@ -188,7 +188,7 @@ function ratio(a::TrialEstimate, b::TrialEstimate)
 end
 
 gcratio(t::TrialEstimate) =  ratio(gctime(t), realtime(t))
-cpuratio(t::TrialEstimate) =  ratio(cputime(t), realtime(t))
+cpuratio(t::TrialEstimate) =  Timers.ACCURATE_CPUTIME ? ratio(cputime(t), realtime(t)) : NaN
 
 ##################
 # TrialJudgement #
@@ -322,16 +322,24 @@ end
 @compat function Base.show(io::IO, ::MIME"text/plain", t::TrialEstimate)
     println(io, "BenchmarkTools.TrialEstimate: ")
     println(io, "  realtime:         ", prettytime(realtime(t)))
-    println(io, "  cputime:          ", prettytime(cputime(t)), " (", prettypercent(cputime(t) / realtime(t)),")")
-    println(io, "  gctime:           ", prettytime(gctime(t)), " (", prettypercent(gctime(t) / realtime(t)),")")
+    if Timers.ACCURATE_CPUTIME
+        println(io, "  cputime:          ", prettytime(cputime(t)), " (", prettypercent(cpuratio(t)),")")
+    else
+        println(io, "  cputime:          ", "NA on Windows, see docs")
+    end
+    println(io, "  gctime:           ", prettytime(gctime(t)), " (", prettypercent(gcratio(t)),")")
     println(io, "  memory:           ", prettymemory(memory(t)))
     print(io,   "  allocs:           ", allocs(t))
 end
 
 @compat function Base.show(io::IO, ::MIME"text/plain", t::TrialRatio)
     println(io, "BenchmarkTools.TrialRatio: ")
     println(io, "  realtime:         ", realtime(t))
-    println(io, "  cputime:          ", cputime(t))
+    if Timers.ACCURATE_CPUTIME
+        println(io, "  cputime:          ", cputime(t))
+    else
+        println(io, "  cputime:          ", "NA on Windows, see docs")
+    end
     println(io, "  gctime:           ", gctime(t))
     println(io, "  memory:           ", memory(t))
     print(io,   "  allocs:           ", allocs(t))
@@ -340,6 +348,10 @@ end
 @compat function Base.show(io::IO, ::MIME"text/plain", t::TrialJudgement)
     println(io, "BenchmarkTools.TrialJudgement: ")
     println(io, "  realtime: ", prettydiff(realtime(ratio(t))), " => ", realtime(t), " (", prettypercent(params(t).time_tolerance), " tolerance)")
-    println(io, "  cputime:  ", prettydiff(cputime(ratio(t))), " => ", cputime(t), " (", prettypercent(params(t).time_tolerance), " tolerance)")
+    if Timers.ACCURATE_CPUTIME
+        println(io, "  cputime:  ", prettydiff(cputime(ratio(t))), " => ", cputime(t), " (", prettypercent(params(t).time_tolerance), " tolerance)")
+    else
+        println(io, "  cputime:  ", "NA on Windows, see docs")
+    end
     print(io,   "  memory:   ", prettydiff(memory(ratio(t))), " => ", memory(t), " (", prettypercent(params(t).memory_tolerance), " tolerance)")
 end