module Benchmark

Overview

The Benchmark module provides methods for benchmarking Crystal code, giving detailed reports on the time and memory taken for each task.

NOTE To use Benchmark, you must explicitly import it with require "benchmark"

Measure the number of iterations per second of each task

require "benchmark"

Benchmark.ips do |x|
  x.report("short sleep") { sleep 10.milliseconds }
  x.report("shorter sleep") { sleep 1.millisecond }
end

This generates the following output showing the mean iterations per second, the mean times per iteration, the standard deviation relative to the mean, and a comparison:

  short sleep   88.7  ( 11.27ms) (± 3.33%)  8.90× slower
shorter sleep  789.7  (  1.27ms) (± 3.02%)       fastest

Benchmark::IPS defaults to 2 seconds of warmup time and 5 seconds of calculation time. This can be configured:

require "benchmark"

Benchmark.ips(warmup: 4, calculation: 10) do |x|
  x.report("sleep") { sleep 10.milliseconds }
end

Measure the time to construct the string given by the expression: "a"*1_000_000_000

require "benchmark"

puts Benchmark.measure { "a"*1_000_000_000 }

This generates the following output:

 0.190000   0.220000   0.410000 (  0.420185)

This report shows the user CPU time, system CPU time, the sum of the user and system CPU times, and the elapsed real time. The unit of time is seconds.

Do some experiments sequentially using the #bm method:

require "benchmark"

n = 5000000
Benchmark.bm do |x|
  x.report("times:") do
    n.times do
      a = "1"
    end
  end
  x.report("upto:") do
    1.upto(n) do
      a = "1"
    end
  end
end

The result:

           user     system      total        real
times:   0.010000   0.000000   0.010000 (  0.008976)
upto:    0.010000   0.000000   0.010000 (  0.010466)

NOTE Make sure to always benchmark code by compiling with the --release flag.

Extended Modules

Defined in:

benchmark.cr
benchmark/bm.cr
benchmark/ips.cr

Instance Method Summary

Instance Method Detail

def bm(&) #

Main interface of the Benchmark module. Yields a Job to which one can report the benchmarks. See the module's description.


[View source]
def ips(calculation : Time::Span = 5.seconds, warmup : Time::Span = 2.seconds, interactive : Bool = STDOUT.tty?, &) #

Instruction per second interface of the Benchmark module. Yields a Job to which one can report the benchmarks. See the module's description.

The optional parameters calculation and warmup set the duration of those stages. For more detail on these stages see Benchmark::IPS. When the interactive parameter is true, results are displayed and updated as they are calculated, otherwise all at once after they finished.


[View source]
def ips(calculation = 5, warmup = 2, interactive = STDOUT.tty?, &) #

Instruction per second interface of the Benchmark module. Yields a Job to which one can report the benchmarks. See the module's description.

The optional parameters calculation and warmup set the duration of those stages in seconds. For more detail on these stages see Benchmark::IPS. When the interactive parameter is true, results are displayed and updated as they are calculated, otherwise all at once after they finished.

DEPRECATED Use #ips(Time::Span, Time::Span, Bool, &) instead.


[View source]
def measure(label = "", &) : BM::Tms #

Returns the time used to execute the given block.


[View source]
def memory(&) #

Returns the memory in bytes that the given block consumes.

Benchmark.memory { Array(Int32).new } # => 32

[View source]
def realtime(&) : Time::Span #

Returns the elapsed real time used to execute the given block.

Benchmark.realtime { "a" * 100_000 } # => 00:00:00.0005840

[View source]