Merge pull request #383 from singularitti/btimed

Add `@btimed` and `@ballocations` macros

Author: willow-ahrens

docs/src/manual.md

@@ -57,12 +57,11 @@ BenchmarkTools.Trial: 10000 samples with 1000 evaluations.
  Memory estimate: 0 bytes, allocs estimate: 0.
 ```
 
-Alternatively, you can use the `@btime` or `@belapsed` macros.
-These take exactly the same arguments as `@benchmark`, but
-behave like the `@time` or `@elapsed` macros included with
-Julia: `@btime` prints the minimum time and memory allocation
-before returning the value of the expression, while `@belapsed`
-returns the minimum time in seconds.
+Alternatively, you can use the `@btime`, `@btimed`,
+`@belapsed`, `@ballocated`, or `@ballocations` macros. These
+take exactly the same arguments as `@benchmark`, but behave
+like the `@time`, `@timed`, `@elapsed`, `@allocated`, or
+`@allocations` macros included with Julia.
 
 ```julia
 julia> @btime sin(1)
@@ -71,6 +70,15 @@ julia> @btime sin(1)
 
 julia> @belapsed sin(1)
 1.3614228456913828e-8
+
+julia> @btimed sin(1)
+(value = 0.8414709848078965, time = 9.16e-10, bytes = 0, alloc = 0, gctime = 0.0)
+
+julia> @ballocated rand(4, 4)
+208
+
+julia> @ballocations rand(4, 4)
+2
 ```
 
 ### Benchmark `Parameters`

src/BenchmarkTools.jl

@@ -63,7 +63,16 @@ export BenchmarkGroup,
 
 include("execution.jl")
 
-export tune!, warmup, @ballocated, @benchmark, @benchmarkable, @belapsed, @btime, @bprofile
+export tune!,
+    warmup,
+    @ballocated,
+    @ballocations,
+    @benchmark,
+    @benchmarkable,
+    @belapsed,
+    @btime,
+    @btimed,
+    @bprofile
 
 #################
 # Serialization #

src/execution.jl

@@ -641,6 +641,30 @@ macro ballocated(args...)
     )
 end
 
+"""
+    @ballocations expression [other parameters...]
+
+Similar to the `@allocations` macro included with Julia,
+this macro evaluates an expression, discarding the resulting
+value, and returns the total number of allocations made
+during its execution.
+
+Unlike `@allocations`, it uses the `@benchmark` macro from
+the `BenchmarkTools` package, and accepts all of the same
+additional parameters as `@benchmark`. The returned number
+of allocations corresponds to the trial with the *minimum*
+elapsed time measured during the benchmark.
+"""
+macro ballocations(args...)
+    return esc(
+        quote
+            $BenchmarkTools.allocs(
+                $BenchmarkTools.minimum($BenchmarkTools.@benchmark $(args...))
+            )
+        end,
+    )
+end
+
 """
     @btime expression [other parameters...]
 
@@ -684,6 +708,46 @@ macro btime(args...)
     )
 end
 
+"""
+    @btimed expression [other parameters...]
+
+Similar to the `@timed` macro included with Julia, this
+macro executes an expression and returns a `NamedTuple`
+containing the value of the expression, the minimum elapsed
+time in seconds, the total bytes allocated, the number of
+allocations, and the garbage collection time in seconds
+during the benchmark.
+
+Unlike `@timed`, it uses the `@benchmark` macro from the
+`BenchmarkTools` package for more detailed and consistent
+performance measurements. The elapsed time reported is the
+minimum time measured during the benchmark. It accepts all
+additional parameters supported by `@benchmark`.
+"""
+macro btimed(args...)
+    _, params = prunekwargs(args...)
+    bench, trial, result = gensym(), gensym(), gensym()
+    trialmin = gensym()
+    tune_phase = hasevals(params) ? :() : :($BenchmarkTools.tune!($bench))
+    return esc(
+        quote
+            local $bench = $BenchmarkTools.@benchmarkable $(args...)
+            $tune_phase
+            local $trial, $result = $BenchmarkTools.run_result(
+                $bench; warmup=$(hasevals(params))
+            )
+            local $trialmin = $BenchmarkTools.minimum($trial)
+            (
+                value=$result,
+                time=$BenchmarkTools.time($trialmin) / 1e9,  # `@timed` macro returns elapsed time in seconds
+                bytes=$BenchmarkTools.memory($trialmin),
+                alloc=$BenchmarkTools.allocs($trialmin),
+                gctime=$BenchmarkTools.gctime($trialmin) / 1e9,
+            )
+        end,
+    )
+end
+
 """
     @bprofile expression [other parameters...]
 

test/ExecutionTests.jl

@@ -345,6 +345,22 @@ str = String(take!(io))
 @test @ballocated(sin(0)) == 0
 @test @ballocated(Ref(1)) == 2 * sizeof(Int)  # 1 for the pointer, 1 for content
 
+@test @ballocations(sin($(foo.x)), evals = 3, samples = 10, setup = (foo.x = 0)) == 0
+@test @ballocations(sin(0)) == 0
+@test @ballocations(Ref(1)) == 1
+
+@test let stats = @btimed sin($(foo.x)) evals = 3 samples = 10 setup = (foo.x = 0)
+    stats.value == sin(0) &&
+        stats.time > 0 &&
+        stats.bytes == 0 &&
+        stats.alloc == 0 &&
+        stats.gctime == 0
+end
+
+@test let stats = @btimed Ref(1)
+    stats.bytes > 0 && stats.alloc == 1 && stats.gctime == 0
+end
+
 let fname = tempname()
     try
         ret = open(fname, "w") do f