Benchmark::Perf

Gem Version Build Status Build status Code Climate Coverage Status Inline docs

Measure execution time and iterations per second.

The Benchmark::Perf is used by rspec-benchmark

Installation

Add this line to your application's Gemfile:

gem 'benchmark-perf'

And then execute:

$ bundle

Or install it yourself as:

$ gem install benchmark-perf

Contents

1. Usage

To see how long it takes to execute a piece of code do:

result = Benchmark::Perf.cpu { ... }

The result will have information about:

result.avg    # => average time in sec
result.stdev  # => standard deviation in sec
result.dt     # => elapsed time in sec

Or to see how many iterations per second a piece of code takes do:

result = Benchmark::Perf.ips { ... }

Then you can query result for:

result.avg    # => average ips
result.stdev  # => ips stadard deviation
result.iter   # => number of iterations
result.dt     # => elapsed time

2. API

2.1 Execution time

By default 1 measurement is taken, and before that 1 warmup cycle is run.

If you need to change how many measurements are taken, use the :repeat option:

result = Benchmark::Perf.cpu(repeat: 10) { ... }

Then you can query result for the following information:

result.avg    # => average time in sec
result.stdev  # => standard deviation in sec
result.dt     # => elapsed time in sec

Increasing the number of measurements will lead to more stable results at the price of longer runtime.

To change how many warmup cycles are done before measuring, use :warmup option like so:

Benchmark::Perf.cpu(warmup: 2) { ... }

If you're interested in having debug output to see exact measurements for each measurement sample use the :io option and pass alternative stream:

Benchmark::Perf.cpu(io: $stdout) { ... }

By default all measurements are done in subprocess to isolate the measured code from other process activities. Sometimes this may have some unintended consequences. For example, when code uses database connections and transactions, this may lead to lost connections. To switch running in subprocess off, use the :subprocess option:

Benchmark::Perf.cpu(subprocess: false) { ... }

Or use the environment variable RUN_IN_SUBPROCESS to toggle the behaviour.

2.2 Iterations

In order to check how many iterations per second a given code takes do:

reuslt = Benchmark::Perf.ips { ... }

The result contains measurements that you can query:

result.avg    # => average ips
result.stdev  # => ips stadard deviation
result.iter   # => number of iterations
result.dt     # => elapsed time

Alternatively, the result can be deconstructed into variables:

avg, stdev, iter, dt = *result

By default 1 second is spent warming up Ruby VM, you can change this with the :warmup option that expects time value in seconds:

Benchmark::Perf.ips(warmup: 1.45) { ... } # 1.45 second

The measurements are sampled for 2 seconds by default. You can change this value to increase precision using :time option:

Benchmark::Perf.ips(time: 3.5) { ... } # 3.5 seconds

Contributing

  1. Fork it ( https://github.com/piotrmurach/benchmark-perf/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Code of Conduct

Everyone interacting in the Strings project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Copyright (c) 2016 Piotr Murach. See LICENSE for further details.