README.md in benchmark_driver-0.6.1 vs README.md in benchmark_driver-0.6.2
- old
+ new
@@ -16,15 +16,16 @@
- Profiling memory, high-precision real time, ~user time and system time~
### Pluggable & Fully Featured
- Flexible and real-time output format in ips, execution time, ~markdown table~, etc.
-- Output format is pluggable
+- Runner and output are all pluggable
- ~Integrated benchmark support using external libraries~
### Flexible Interface
+- Ruby interface similar to benchmark stdlib, benchmark-ips
- YAML input to easily manage structured benchmark set
- Comparing multiple Ruby binaries, even with miniruby
## Installation
@@ -32,10 +33,62 @@
$ gem install benchmark_driver
```
## Usage
+### Ruby Interface: Compatible Mode
+
+This interface is compatible with `Benchmark.bm` and `Benchmark.ips`, so it's good for migration.
+
+```rb
+require 'benchmark/driver'
+require 'active_support/all'
+array = []
+
+Benchmark.driver do |x|
+ x.report('blank?') { array.blank? }
+ x.report('empty?') { array.empty? }
+ x.compare!
+end
+```
+
+### Ruby Interface: Low Overhead Mode
+
+This interface generates code to profile with low overhead and executes it.
+
+```rb
+require 'benchmark/driver'
+
+Benchmark.driver do |x|
+ x.prelude = <<~RUBY
+ require 'active_support/all'
+ array = []
+ RUBY
+
+ x.report('blank?', script: 'array.blank?')
+ x.report('empty?', script: 'array.empty?')
+end
+```
+
+or simply:
+
+```rb
+require 'benchmark/driver'
+
+Benchmark.driver do |x|
+ x.prelude = <<~RUBY
+ require 'active_support/all'
+ array = []
+ RUBY
+
+ x.report(script: 'array.blank?')
+ x.report(script: 'array.empty?')
+end
+```
+
+### Structured YAML Input
+
With `benchmark-driver` command, you can describe benchmark with YAML input.
```
$ benchmark-driver -h
Usage: benchmark-driver [options] [YAML]
@@ -43,11 +96,11 @@
--rbenv [VERSIONS] Ruby executables in rbenv (2.3.5;2.4.2;...)
-c, --compare Compare results (currently only supported in ips output)
-r, --repeat-count [NUM] Try benchmark NUM times and use the fastest result
```
-### Running single script
+#### Running single script
With following `example_single.yml`,
```yml
prelude: |
@@ -69,11 +122,11 @@
Comparison:
erb.result (trunk): 123611.1 i/s
erb.result (2.4.2): 109268.4 i/s - 1.13x slower
```
-### Running multiple scripts
+#### Running multiple scripts
One YAML file can contain multiple benchmark scripts.
With following `example_multi.yml`,
```yml
@@ -104,17 +157,18 @@
str-interp (2.4.2): 4305563.1 i/s - 1.40x slower
```
## TODO
### Runner
+- [x] Call
- [x] Exec
- [ ] Eval
### Output
- [x] IPS
- [x] Time
-- [x] Memory
- [ ] CPU/System/Real Time
+- [ ] Memory
- [ ] Markdown Table
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/k0kubun/benchmark_driver.