# Benchmark::Perf

[![Gem Version](https://badge.fury.io/rb/benchmark-perf.svg)][gem]
[![Build Status](https://secure.travis-ci.org/piotrmurach/benchmark-perf.svg?branch=master)][travis]
[![Build status](https://ci.appveyor.com/api/projects/status/wv37qw3x5l9km5kl?svg=true)][appveyor]
[![Code Climate](https://codeclimate.com/github/piotrmurach/benchmark-perf/badges/gpa.svg)][codeclimate]
[![Coverage Status](https://coveralls.io/repos/github/piotrmurach/benchmark-perf/badge.svg?branch=master)][coverage]
[![Inline docs](http://inch-ci.org/github/piotrmurach/benchmark-perf.svg?branch=master)][inchpages]

[gem]: http://badge.fury.io/rb/benchmark-perf
[travis]: http://travis-ci.org/piotrmurach/benchmark-perf
[appveyor]: https://ci.appveyor.com/project/piotrmurach/benchmark-perf
[codeclimate]: https://codeclimate.com/github/piotrmurach/benchmark-perf
[coverage]: https://coveralls.io/github/piotrmurach/benchmark-perf?branch=master
[inchpages]: http://inch-ci.org/github/piotrmurach/benchmark-perf

> Measure execution time and iterations per second.

The **Benchmark::Perf** is used by [rspec-benchmark](https://github.com/piotrmurach/rspec-benchmark)

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'benchmark-perf'
```

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install benchmark-perf

## Contents

* [1. Usage](#1-usage)
* [2. API](#2-api)
  * [2.1 Execution time](#21-execution-time)
  * [2.2 Iterations](#22-iterations)

## 1. Usage

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

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

The result will have information about:

```ruby
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:

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

Then you can query result for:

```ruby
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:

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

Then you can query result for the following information:

```ruby
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:

```ruby
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:

```ruby
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:

```ruby
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:

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

The result contains measurements that you can query:

```ruby
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:

```ruby
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:

```ruby
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:

```ruby
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](https://github.com/piotrmurach/benchmark-perf/blob/master/CODE_OF_CONDUCT.md).

## Copyright

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