File: C:/Ruby27-x64/share/doc/ruby/html/Benchmark.html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>module Benchmark - RDoc Documentation</title>
<script type="text/javascript">
var rdoc_rel_prefix = "./";
var index_rel_prefix = "./";
</script>
<script src="./js/navigation.js" defer></script>
<script src="./js/search.js" defer></script>
<script src="./js/search_index.js" defer></script>
<script src="./js/searcher.js" defer></script>
<script src="./js/darkfish.js" defer></script>
<link href="./css/fonts.css" rel="stylesheet">
<link href="./css/rdoc.css" rel="stylesheet">
<body id="top" role="document" class="module">
<nav role="navigation">
<div id="project-navigation">
<div id="home-section" role="region" title="Quick navigation" class="nav-section">
<h2>
<a href="./index.html" rel="home">Home</a>
</h2>
<div id="table-of-contents-navigation">
<a href="./table_of_contents.html#pages">Pages</a>
<a href="./table_of_contents.html#classes">Classes</a>
<a href="./table_of_contents.html#methods">Methods</a>
</div>
</div>
<div id="search-section" role="search" class="project-section initially-hidden">
<form action="#" method="get" accept-charset="utf-8">
<div id="search-field-wrapper">
<input id="search-field" role="combobox" aria-label="Search"
aria-autocomplete="list" aria-controls="search-results"
type="text" name="search" placeholder="Search" spellcheck="false"
title="Type to search, Up and Down to navigate, Enter to load">
</div>
<ul id="search-results" aria-label="Search Results"
aria-busy="false" aria-expanded="false"
aria-atomic="false" class="initially-hidden"></ul>
</form>
</div>
</div>
<div id="class-metadata">
<!-- Method Quickref -->
<div id="method-list-section" class="nav-section">
<h3>Methods</h3>
<ul class="link-list" role="directory">
<li ><a href="#method-c-benchmark">::benchmark</a>
<li ><a href="#method-c-bm">::bm</a>
<li ><a href="#method-c-bmbm">::bmbm</a>
<li ><a href="#method-c-measure">::measure</a>
<li ><a href="#method-c-realtime">::realtime</a>
<li ><a href="#method-i-benchmark">#benchmark</a>
<li ><a href="#method-i-bm">#bm</a>
<li ><a href="#method-i-bmbm">#bmbm</a>
<li ><a href="#method-i-measure">#measure</a>
<li ><a href="#method-i-realtime">#realtime</a>
</ul>
</div>
</div>
</nav>
<main role="main" aria-labelledby="module-Benchmark">
<h1 id="module-Benchmark" class="module">
module Benchmark
</h1>
<section class="description">
<p>The <a href="Benchmark.html"><code>Benchmark</code></a> module provides methods to measure and report the time used to execute Ruby code.</p>
<ul><li>
<p>Measure the time to construct the string given by the expression <code>"a"*1_000_000_000</code>:</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'benchmark'</span>
<span class="ruby-identifier">puts</span> <span class="ruby-constant">Benchmark</span>.<span class="ruby-identifier">measure</span> { <span class="ruby-string">"a"</span><span class="ruby-operator">*</span><span class="ruby-value">1_000_000_000</span> }
</pre>
<p>On my machine (OSX 10.8.3 on i5 1.7 GHz) this generates:</p>
<pre>0.350000 0.400000 0.750000 ( 0.835234)</pre>
<p>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.</p>
</li><li>
<p>Do some experiments sequentially using the <a href="Benchmark.html#method-i-bm"><code>bm</code></a> method:</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'benchmark'</span>
<span class="ruby-identifier">n</span> = <span class="ruby-value">5000000</span>
<span class="ruby-constant">Benchmark</span>.<span class="ruby-identifier">bm</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">x</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span> { <span class="ruby-keyword">for</span> <span class="ruby-identifier">i</span> <span class="ruby-keyword">in</span> <span class="ruby-value">1</span><span class="ruby-operator">..</span><span class="ruby-identifier">n</span>; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span> { <span class="ruby-identifier">n</span>.<span class="ruby-identifier">times</span> <span class="ruby-keyword">do</span> ; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span> { <span class="ruby-value">1</span>.<span class="ruby-identifier">upto</span>(<span class="ruby-identifier">n</span>) <span class="ruby-keyword">do</span> ; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-keyword">end</span>
</pre>
<p>The result:</p>
<pre> user system total real
1.010000 0.000000 1.010000 ( 1.014479)
1.000000 0.000000 1.000000 ( 0.998261)
0.980000 0.000000 0.980000 ( 0.981335)</pre>
</li><li>
<p>Continuing the previous example, put a label in each report:</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'benchmark'</span>
<span class="ruby-identifier">n</span> = <span class="ruby-value">5000000</span>
<span class="ruby-constant">Benchmark</span>.<span class="ruby-identifier">bm</span>(<span class="ruby-value">7</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">x</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"for:"</span>) { <span class="ruby-keyword">for</span> <span class="ruby-identifier">i</span> <span class="ruby-keyword">in</span> <span class="ruby-value">1</span><span class="ruby-operator">..</span><span class="ruby-identifier">n</span>; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"times:"</span>) { <span class="ruby-identifier">n</span>.<span class="ruby-identifier">times</span> <span class="ruby-keyword">do</span> ; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"upto:"</span>) { <span class="ruby-value">1</span>.<span class="ruby-identifier">upto</span>(<span class="ruby-identifier">n</span>) <span class="ruby-keyword">do</span> ; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-keyword">end</span>
</pre>
</li></ul>
<p>The result:</p>
<pre> user system total real
for: 1.010000 0.000000 1.010000 ( 1.015688)
times: 1.000000 0.000000 1.000000 ( 1.003611)
upto: 1.030000 0.000000 1.030000 ( 1.028098)</pre>
<ul><li>
<p>The times for some benchmarks depend on the order in which items are run. These differences are due to the cost of memory allocation and garbage collection. To avoid these discrepancies, the <a href="Benchmark.html#method-i-bmbm"><code>bmbm</code></a> method is provided. For example, to compare ways to sort an array of floats:</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'benchmark'</span>
<span class="ruby-identifier">array</span> = (<span class="ruby-value">1</span><span class="ruby-operator">..</span><span class="ruby-value">1000000</span>).<span class="ruby-identifier">map</span> { <span class="ruby-identifier">rand</span> }
<span class="ruby-constant">Benchmark</span>.<span class="ruby-identifier">bmbm</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">x</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"sort!"</span>) { <span class="ruby-identifier">array</span>.<span class="ruby-identifier">dup</span>.<span class="ruby-identifier">sort!</span> }
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"sort"</span>) { <span class="ruby-identifier">array</span>.<span class="ruby-identifier">dup</span>.<span class="ruby-identifier">sort</span> }
<span class="ruby-keyword">end</span>
</pre>
<p>The result:</p>
<pre>Rehearsal -----------------------------------------
sort! 1.490000 0.010000 1.500000 ( 1.490520)
sort 1.460000 0.000000 1.460000 ( 1.463025)
-------------------------------- total: 2.960000sec
user system total real
sort! 1.460000 0.000000 1.460000 ( 1.460465)
sort 1.450000 0.010000 1.460000 ( 1.448327)</pre>
</li><li>
<p>Report statistics of sequential experiments with unique labels, using the <a href="Benchmark.html#method-i-benchmark"><code>benchmark</code></a> method:</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'benchmark'</span>
<span class="ruby-identifier">include</span> <span class="ruby-constant">Benchmark</span> <span class="ruby-comment"># we need the CAPTION and FORMAT constants</span>
<span class="ruby-identifier">n</span> = <span class="ruby-value">5000000</span>
<span class="ruby-constant">Benchmark</span>.<span class="ruby-identifier">benchmark</span>(<span class="ruby-constant">CAPTION</span>, <span class="ruby-value">7</span>, <span class="ruby-constant">FORMAT</span>, <span class="ruby-string">">total:"</span>, <span class="ruby-string">">avg:"</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">x</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">tf</span> = <span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"for:"</span>) { <span class="ruby-keyword">for</span> <span class="ruby-identifier">i</span> <span class="ruby-keyword">in</span> <span class="ruby-value">1</span><span class="ruby-operator">..</span><span class="ruby-identifier">n</span>; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-identifier">tt</span> = <span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"times:"</span>) { <span class="ruby-identifier">n</span>.<span class="ruby-identifier">times</span> <span class="ruby-keyword">do</span> ; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-identifier">tu</span> = <span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"upto:"</span>) { <span class="ruby-value">1</span>.<span class="ruby-identifier">upto</span>(<span class="ruby-identifier">n</span>) <span class="ruby-keyword">do</span> ; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
[<span class="ruby-identifier">tf</span><span class="ruby-operator">+</span><span class="ruby-identifier">tt</span><span class="ruby-operator">+</span><span class="ruby-identifier">tu</span>, (<span class="ruby-identifier">tf</span><span class="ruby-operator">+</span><span class="ruby-identifier">tt</span><span class="ruby-operator">+</span><span class="ruby-identifier">tu</span>)<span class="ruby-operator">/</span><span class="ruby-value">3</span>]
<span class="ruby-keyword">end</span>
</pre>
<p>The result:</p>
<pre> user system total real
for: 0.950000 0.000000 0.950000 ( 0.952039)
times: 0.980000 0.000000 0.980000 ( 0.984938)
upto: 0.950000 0.000000 0.950000 ( 0.946787)
>total: 2.880000 0.000000 2.880000 ( 2.883764)
>avg: 0.960000 0.000000 0.960000 ( 0.961255)</pre>
</li></ul>
</section>
<section id="5Buntitled-5D" class="documentation-section">
<section class="constants-list">
<header>
<h3>Constants</h3>
</header>
<dl>
<dt id="CAPTION">CAPTION
<dd><p>The default caption string (heading above the output times).</p>
<dt id="FORMAT">FORMAT
<dd><p>The default format string used to display times. See also <a href="Benchmark/Tms.html#method-i-format"><code>Benchmark::Tms#format</code></a>.</p>
</dl>
</section>
<section id="public-class-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Class Methods</h3>
</header>
<div id="method-c-benchmark" class="method-detail ">
<div class="method-heading">
<span class="method-name">benchmark</span><span
class="method-args">(caption = "", label_width = nil, format = nil, *labels) { |report| ... }</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Invokes the block with a Benchmark::Report object, which may be used to collect and report on the results of individual benchmark tests. Reserves <code>label_width</code> leading spaces for labels on each line. Prints <code>caption</code> at the top of the report, and uses <code>format</code> to format each line. Returns an array of <a href="Benchmark/Tms.html"><code>Benchmark::Tms</code></a> objects.</p>
<p>If the block returns an array of <a href="Benchmark/Tms.html"><code>Benchmark::Tms</code></a> objects, these will be used to format additional lines of output. If <code>labels</code> parameter are given, these are used to label these extra lines.</p>
<p><em>Note</em>: Other methods provide a simpler interface to this one, and are suitable for nearly all benchmarking requirements. See the examples in <a href="Benchmark.html"><code>Benchmark</code></a>, and the <a href="Benchmark.html#method-i-bm"><code>bm</code></a> and <a href="Benchmark.html#method-i-bmbm"><code>bmbm</code></a> methods.</p>
<p>Example:</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'benchmark'</span>
<span class="ruby-identifier">include</span> <span class="ruby-constant">Benchmark</span> <span class="ruby-comment"># we need the CAPTION and FORMAT constants</span>
<span class="ruby-identifier">n</span> = <span class="ruby-value">5000000</span>
<span class="ruby-constant">Benchmark</span>.<span class="ruby-identifier">benchmark</span>(<span class="ruby-constant">CAPTION</span>, <span class="ruby-value">7</span>, <span class="ruby-constant">FORMAT</span>, <span class="ruby-string">">total:"</span>, <span class="ruby-string">">avg:"</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">x</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">tf</span> = <span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"for:"</span>) { <span class="ruby-keyword">for</span> <span class="ruby-identifier">i</span> <span class="ruby-keyword">in</span> <span class="ruby-value">1</span><span class="ruby-operator">..</span><span class="ruby-identifier">n</span>; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-identifier">tt</span> = <span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"times:"</span>) { <span class="ruby-identifier">n</span>.<span class="ruby-identifier">times</span> <span class="ruby-keyword">do</span> ; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-identifier">tu</span> = <span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"upto:"</span>) { <span class="ruby-value">1</span>.<span class="ruby-identifier">upto</span>(<span class="ruby-identifier">n</span>) <span class="ruby-keyword">do</span> ; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
[<span class="ruby-identifier">tf</span><span class="ruby-operator">+</span><span class="ruby-identifier">tt</span><span class="ruby-operator">+</span><span class="ruby-identifier">tu</span>, (<span class="ruby-identifier">tf</span><span class="ruby-operator">+</span><span class="ruby-identifier">tt</span><span class="ruby-operator">+</span><span class="ruby-identifier">tu</span>)<span class="ruby-operator">/</span><span class="ruby-value">3</span>]
<span class="ruby-keyword">end</span>
</pre>
<p>Generates:</p>
<pre> user system total real
for: 0.970000 0.000000 0.970000 ( 0.970493)
times: 0.990000 0.000000 0.990000 ( 0.989542)
upto: 0.970000 0.000000 0.970000 ( 0.972854)
>total: 2.930000 0.000000 2.930000 ( 2.932889)
>avg: 0.976667 0.000000 0.976667 ( 0.977630)</pre>
<div class="method-source-code" id="benchmark-source">
<pre><span class="ruby-comment"># File lib/benchmark.rb, line 165</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">benchmark</span>(<span class="ruby-identifier">caption</span> = <span class="ruby-string">""</span>, <span class="ruby-identifier">label_width</span> = <span class="ruby-keyword">nil</span>, <span class="ruby-identifier">format</span> = <span class="ruby-keyword">nil</span>, <span class="ruby-operator">*</span><span class="ruby-identifier">labels</span>) <span class="ruby-comment"># :yield: report</span>
<span class="ruby-identifier">sync</span> = <span class="ruby-constant">STDOUT</span>.<span class="ruby-identifier">sync</span>
<span class="ruby-constant">STDOUT</span>.<span class="ruby-identifier">sync</span> = <span class="ruby-keyword">true</span>
<span class="ruby-identifier">label_width</span> <span class="ruby-operator">||=</span> <span class="ruby-value">0</span>
<span class="ruby-identifier">label_width</span> <span class="ruby-operator">+=</span> <span class="ruby-value">1</span>
<span class="ruby-identifier">format</span> <span class="ruby-operator">||=</span> <span class="ruby-constant">FORMAT</span>
<span class="ruby-identifier">print</span> <span class="ruby-string">' '</span><span class="ruby-operator">*</span><span class="ruby-identifier">label_width</span> <span class="ruby-operator">+</span> <span class="ruby-identifier">caption</span> <span class="ruby-keyword">unless</span> <span class="ruby-identifier">caption</span>.<span class="ruby-identifier">empty?</span>
<span class="ruby-identifier">report</span> = <span class="ruby-constant">Report</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">label_width</span>, <span class="ruby-identifier">format</span>)
<span class="ruby-identifier">results</span> = <span class="ruby-keyword">yield</span>(<span class="ruby-identifier">report</span>)
<span class="ruby-constant">Array</span> <span class="ruby-operator">===</span> <span class="ruby-identifier">results</span> <span class="ruby-keyword">and</span> <span class="ruby-identifier">results</span>.<span class="ruby-identifier">grep</span>(<span class="ruby-constant">Tms</span>).<span class="ruby-identifier">each</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">t</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">print</span>((<span class="ruby-identifier">labels</span>.<span class="ruby-identifier">shift</span> <span class="ruby-operator">||</span> <span class="ruby-identifier">t</span>.<span class="ruby-identifier">label</span> <span class="ruby-operator">||</span> <span class="ruby-string">""</span>).<span class="ruby-identifier">ljust</span>(<span class="ruby-identifier">label_width</span>), <span class="ruby-identifier">t</span>.<span class="ruby-identifier">format</span>(<span class="ruby-identifier">format</span>))
}
<span class="ruby-identifier">report</span>.<span class="ruby-identifier">list</span>
<span class="ruby-keyword">ensure</span>
<span class="ruby-constant">STDOUT</span>.<span class="ruby-identifier">sync</span> = <span class="ruby-identifier">sync</span> <span class="ruby-keyword">unless</span> <span class="ruby-identifier">sync</span>.<span class="ruby-identifier">nil?</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-c-bm" class="method-detail ">
<div class="method-heading">
<span class="method-name">bm</span><span
class="method-args">(label_width = 0, *labels) { |report| ... }</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>A simple interface to the <a href="Benchmark.html#method-i-benchmark"><code>benchmark</code></a> method, <a href="Benchmark.html#method-i-bm"><code>bm</code></a> generates sequential reports with labels. <code>label_width</code> and <code>labels</code> parameters have the same meaning as for <a href="Benchmark.html#method-i-benchmark"><code>benchmark</code></a>.</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'benchmark'</span>
<span class="ruby-identifier">n</span> = <span class="ruby-value">5000000</span>
<span class="ruby-constant">Benchmark</span>.<span class="ruby-identifier">bm</span>(<span class="ruby-value">7</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">x</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"for:"</span>) { <span class="ruby-keyword">for</span> <span class="ruby-identifier">i</span> <span class="ruby-keyword">in</span> <span class="ruby-value">1</span><span class="ruby-operator">..</span><span class="ruby-identifier">n</span>; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"times:"</span>) { <span class="ruby-identifier">n</span>.<span class="ruby-identifier">times</span> <span class="ruby-keyword">do</span> ; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"upto:"</span>) { <span class="ruby-value">1</span>.<span class="ruby-identifier">upto</span>(<span class="ruby-identifier">n</span>) <span class="ruby-keyword">do</span> ; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-keyword">end</span>
</pre>
<p>Generates:</p>
<pre> user system total real
for: 0.960000 0.000000 0.960000 ( 0.957966)
times: 0.960000 0.000000 0.960000 ( 0.960423)
upto: 0.950000 0.000000 0.950000 ( 0.954864)</pre>
<div class="method-source-code" id="bm-source">
<pre><span class="ruby-comment"># File lib/benchmark.rb, line 204</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">bm</span>(<span class="ruby-identifier">label_width</span> = <span class="ruby-value">0</span>, <span class="ruby-operator">*</span><span class="ruby-identifier">labels</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">blk</span>) <span class="ruby-comment"># :yield: report</span>
<span class="ruby-identifier">benchmark</span>(<span class="ruby-constant">CAPTION</span>, <span class="ruby-identifier">label_width</span>, <span class="ruby-constant">FORMAT</span>, <span class="ruby-operator">*</span><span class="ruby-identifier">labels</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">blk</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-c-bmbm" class="method-detail ">
<div class="method-heading">
<span class="method-name">bmbm</span><span
class="method-args">(width = 0) { |job| ... }</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Sometimes benchmark results are skewed because code executed earlier encounters different garbage collection overheads than that run later. <a href="Benchmark.html#method-i-bmbm"><code>bmbm</code></a> attempts to minimize this effect by running the tests twice, the first time as a rehearsal in order to get the runtime environment stable, the second time for real. <a href="GC.html#method-c-start"><code>GC.start</code></a> is executed before the start of each of the real timings; the cost of this is not included in the timings. In reality, though, there's only so much that <a href="Benchmark.html#method-i-bmbm"><code>bmbm</code></a> can do, and the results are not guaranteed to be isolated from garbage collection and other effects.</p>
<p>Because <a href="Benchmark.html#method-i-bmbm"><code>bmbm</code></a> takes two passes through the tests, it can calculate the required label width.</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'benchmark'</span>
<span class="ruby-identifier">array</span> = (<span class="ruby-value">1</span><span class="ruby-operator">..</span><span class="ruby-value">1000000</span>).<span class="ruby-identifier">map</span> { <span class="ruby-identifier">rand</span> }
<span class="ruby-constant">Benchmark</span>.<span class="ruby-identifier">bmbm</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">x</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"sort!"</span>) { <span class="ruby-identifier">array</span>.<span class="ruby-identifier">dup</span>.<span class="ruby-identifier">sort!</span> }
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"sort"</span>) { <span class="ruby-identifier">array</span>.<span class="ruby-identifier">dup</span>.<span class="ruby-identifier">sort</span> }
<span class="ruby-keyword">end</span>
</pre>
<p>Generates:</p>
<pre>Rehearsal -----------------------------------------
sort! 1.440000 0.010000 1.450000 ( 1.446833)
sort 1.440000 0.000000 1.440000 ( 1.448257)
-------------------------------- total: 2.890000sec
user system total real
sort! 1.460000 0.000000 1.460000 ( 1.458065)
sort 1.450000 0.000000 1.450000 ( 1.455963)</pre>
<p><a href="Benchmark.html#method-i-bmbm"><code>bmbm</code></a> yields a Benchmark::Job object and returns an array of <a href="Benchmark/Tms.html"><code>Benchmark::Tms</code></a> objects.</p>
<div class="method-source-code" id="bmbm-source">
<pre><span class="ruby-comment"># File lib/benchmark.rb, line 246</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">bmbm</span>(<span class="ruby-identifier">width</span> = <span class="ruby-value">0</span>) <span class="ruby-comment"># :yield: job</span>
<span class="ruby-identifier">job</span> = <span class="ruby-constant">Job</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">width</span>)
<span class="ruby-keyword">yield</span>(<span class="ruby-identifier">job</span>)
<span class="ruby-identifier">width</span> = <span class="ruby-identifier">job</span>.<span class="ruby-identifier">width</span> <span class="ruby-operator">+</span> <span class="ruby-value">1</span>
<span class="ruby-identifier">sync</span> = <span class="ruby-constant">STDOUT</span>.<span class="ruby-identifier">sync</span>
<span class="ruby-constant">STDOUT</span>.<span class="ruby-identifier">sync</span> = <span class="ruby-keyword">true</span>
<span class="ruby-comment"># rehearsal</span>
<span class="ruby-identifier">puts</span> <span class="ruby-string">'Rehearsal '</span>.<span class="ruby-identifier">ljust</span>(<span class="ruby-identifier">width</span><span class="ruby-operator">+</span><span class="ruby-constant">CAPTION</span>.<span class="ruby-identifier">length</span>,<span class="ruby-string">'-'</span>)
<span class="ruby-identifier">ets</span> = <span class="ruby-identifier">job</span>.<span class="ruby-identifier">list</span>.<span class="ruby-identifier">inject</span>(<span class="ruby-constant">Tms</span>.<span class="ruby-identifier">new</span>) { <span class="ruby-operator">|</span><span class="ruby-identifier">sum</span>,(<span class="ruby-identifier">label</span>,<span class="ruby-identifier">item</span>)<span class="ruby-operator">|</span>
<span class="ruby-identifier">print</span> <span class="ruby-identifier">label</span>.<span class="ruby-identifier">ljust</span>(<span class="ruby-identifier">width</span>)
<span class="ruby-identifier">res</span> = <span class="ruby-constant">Benchmark</span>.<span class="ruby-identifier">measure</span>(<span class="ruby-operator">&</span><span class="ruby-identifier">item</span>)
<span class="ruby-identifier">print</span> <span class="ruby-identifier">res</span>.<span class="ruby-identifier">format</span>
<span class="ruby-identifier">sum</span> <span class="ruby-operator">+</span> <span class="ruby-identifier">res</span>
}.<span class="ruby-identifier">format</span>(<span class="ruby-string">"total: %tsec"</span>)
<span class="ruby-identifier">print</span> <span class="ruby-node">" #{ets}\n\n"</span>.<span class="ruby-identifier">rjust</span>(<span class="ruby-identifier">width</span><span class="ruby-operator">+</span><span class="ruby-constant">CAPTION</span>.<span class="ruby-identifier">length</span><span class="ruby-value">+2</span>,<span class="ruby-string">'-'</span>)
<span class="ruby-comment"># take</span>
<span class="ruby-identifier">print</span> <span class="ruby-string">' '</span><span class="ruby-operator">*</span><span class="ruby-identifier">width</span> <span class="ruby-operator">+</span> <span class="ruby-constant">CAPTION</span>
<span class="ruby-identifier">job</span>.<span class="ruby-identifier">list</span>.<span class="ruby-identifier">map</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">label</span>,<span class="ruby-identifier">item</span><span class="ruby-operator">|</span>
<span class="ruby-constant">GC</span>.<span class="ruby-identifier">start</span>
<span class="ruby-identifier">print</span> <span class="ruby-identifier">label</span>.<span class="ruby-identifier">ljust</span>(<span class="ruby-identifier">width</span>)
<span class="ruby-constant">Benchmark</span>.<span class="ruby-identifier">measure</span>(<span class="ruby-identifier">label</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">item</span>).<span class="ruby-identifier">tap</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">res</span><span class="ruby-operator">|</span> <span class="ruby-identifier">print</span> <span class="ruby-identifier">res</span> }
}
<span class="ruby-keyword">ensure</span>
<span class="ruby-constant">STDOUT</span>.<span class="ruby-identifier">sync</span> = <span class="ruby-identifier">sync</span> <span class="ruby-keyword">unless</span> <span class="ruby-identifier">sync</span>.<span class="ruby-identifier">nil?</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-c-measure" class="method-detail ">
<div class="method-heading">
<span class="method-name">measure</span><span
class="method-args">(label = "") { || ... }</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the time used to execute the given block as a <a href="Benchmark/Tms.html"><code>Benchmark::Tms</code></a> object. Takes <code>label</code> option.</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'benchmark'</span>
<span class="ruby-identifier">n</span> = <span class="ruby-value">1000000</span>
<span class="ruby-identifier">time</span> = <span class="ruby-constant">Benchmark</span>.<span class="ruby-identifier">measure</span> <span class="ruby-keyword">do</span>
<span class="ruby-identifier">n</span>.<span class="ruby-identifier">times</span> { <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span> }
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">puts</span> <span class="ruby-identifier">time</span>
</pre>
<p>Generates:</p>
<pre>0.220000 0.000000 0.220000 ( 0.227313)</pre>
<div class="method-source-code" id="measure-source">
<pre><span class="ruby-comment"># File lib/benchmark.rb, line 291</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">measure</span>(<span class="ruby-identifier">label</span> = <span class="ruby-string">""</span>) <span class="ruby-comment"># :yield:</span>
<span class="ruby-identifier">t0</span>, <span class="ruby-identifier">r0</span> = <span class="ruby-constant">Process</span>.<span class="ruby-identifier">times</span>, <span class="ruby-constant">Process</span>.<span class="ruby-identifier">clock_gettime</span>(<span class="ruby-constant">Process</span><span class="ruby-operator">::</span><span class="ruby-constant">CLOCK_MONOTONIC</span>)
<span class="ruby-keyword">yield</span>
<span class="ruby-identifier">t1</span>, <span class="ruby-identifier">r1</span> = <span class="ruby-constant">Process</span>.<span class="ruby-identifier">times</span>, <span class="ruby-constant">Process</span>.<span class="ruby-identifier">clock_gettime</span>(<span class="ruby-constant">Process</span><span class="ruby-operator">::</span><span class="ruby-constant">CLOCK_MONOTONIC</span>)
<span class="ruby-constant">Benchmark</span><span class="ruby-operator">::</span><span class="ruby-constant">Tms</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">t1</span>.<span class="ruby-identifier">utime</span> <span class="ruby-operator">-</span> <span class="ruby-identifier">t0</span>.<span class="ruby-identifier">utime</span>,
<span class="ruby-identifier">t1</span>.<span class="ruby-identifier">stime</span> <span class="ruby-operator">-</span> <span class="ruby-identifier">t0</span>.<span class="ruby-identifier">stime</span>,
<span class="ruby-identifier">t1</span>.<span class="ruby-identifier">cutime</span> <span class="ruby-operator">-</span> <span class="ruby-identifier">t0</span>.<span class="ruby-identifier">cutime</span>,
<span class="ruby-identifier">t1</span>.<span class="ruby-identifier">cstime</span> <span class="ruby-operator">-</span> <span class="ruby-identifier">t0</span>.<span class="ruby-identifier">cstime</span>,
<span class="ruby-identifier">r1</span> <span class="ruby-operator">-</span> <span class="ruby-identifier">r0</span>,
<span class="ruby-identifier">label</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-c-realtime" class="method-detail ">
<div class="method-heading">
<span class="method-name">realtime</span><span
class="method-args">() { || ... }</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the elapsed real time used to execute the given block.</p>
<div class="method-source-code" id="realtime-source">
<pre><span class="ruby-comment"># File lib/benchmark.rb, line 306</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">realtime</span> <span class="ruby-comment"># :yield:</span>
<span class="ruby-identifier">r0</span> = <span class="ruby-constant">Process</span>.<span class="ruby-identifier">clock_gettime</span>(<span class="ruby-constant">Process</span><span class="ruby-operator">::</span><span class="ruby-constant">CLOCK_MONOTONIC</span>)
<span class="ruby-keyword">yield</span>
<span class="ruby-constant">Process</span>.<span class="ruby-identifier">clock_gettime</span>(<span class="ruby-constant">Process</span><span class="ruby-operator">::</span><span class="ruby-constant">CLOCK_MONOTONIC</span>) <span class="ruby-operator">-</span> <span class="ruby-identifier">r0</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
</section>
<section id="private-instance-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Private Instance Methods</h3>
</header>
<div id="method-i-benchmark" class="method-detail ">
<div class="method-heading">
<span class="method-name">benchmark</span><span
class="method-args">(caption = "", label_width = nil, format = nil, *labels) { |report| ... }</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Invokes the block with a Benchmark::Report object, which may be used to collect and report on the results of individual benchmark tests. Reserves <code>label_width</code> leading spaces for labels on each line. Prints <code>caption</code> at the top of the report, and uses <code>format</code> to format each line. Returns an array of <a href="Benchmark/Tms.html"><code>Benchmark::Tms</code></a> objects.</p>
<p>If the block returns an array of <a href="Benchmark/Tms.html"><code>Benchmark::Tms</code></a> objects, these will be used to format additional lines of output. If <code>labels</code> parameter are given, these are used to label these extra lines.</p>
<p><em>Note</em>: Other methods provide a simpler interface to this one, and are suitable for nearly all benchmarking requirements. See the examples in <a href="Benchmark.html"><code>Benchmark</code></a>, and the <a href="Benchmark.html#method-i-bm"><code>bm</code></a> and <a href="Benchmark.html#method-i-bmbm"><code>bmbm</code></a> methods.</p>
<p>Example:</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'benchmark'</span>
<span class="ruby-identifier">include</span> <span class="ruby-constant">Benchmark</span> <span class="ruby-comment"># we need the CAPTION and FORMAT constants</span>
<span class="ruby-identifier">n</span> = <span class="ruby-value">5000000</span>
<span class="ruby-constant">Benchmark</span>.<span class="ruby-identifier">benchmark</span>(<span class="ruby-constant">CAPTION</span>, <span class="ruby-value">7</span>, <span class="ruby-constant">FORMAT</span>, <span class="ruby-string">">total:"</span>, <span class="ruby-string">">avg:"</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">x</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">tf</span> = <span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"for:"</span>) { <span class="ruby-keyword">for</span> <span class="ruby-identifier">i</span> <span class="ruby-keyword">in</span> <span class="ruby-value">1</span><span class="ruby-operator">..</span><span class="ruby-identifier">n</span>; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-identifier">tt</span> = <span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"times:"</span>) { <span class="ruby-identifier">n</span>.<span class="ruby-identifier">times</span> <span class="ruby-keyword">do</span> ; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-identifier">tu</span> = <span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"upto:"</span>) { <span class="ruby-value">1</span>.<span class="ruby-identifier">upto</span>(<span class="ruby-identifier">n</span>) <span class="ruby-keyword">do</span> ; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
[<span class="ruby-identifier">tf</span><span class="ruby-operator">+</span><span class="ruby-identifier">tt</span><span class="ruby-operator">+</span><span class="ruby-identifier">tu</span>, (<span class="ruby-identifier">tf</span><span class="ruby-operator">+</span><span class="ruby-identifier">tt</span><span class="ruby-operator">+</span><span class="ruby-identifier">tu</span>)<span class="ruby-operator">/</span><span class="ruby-value">3</span>]
<span class="ruby-keyword">end</span>
</pre>
<p>Generates:</p>
<pre> user system total real
for: 0.970000 0.000000 0.970000 ( 0.970493)
times: 0.990000 0.000000 0.990000 ( 0.989542)
upto: 0.970000 0.000000 0.970000 ( 0.972854)
>total: 2.930000 0.000000 2.930000 ( 2.932889)
>avg: 0.976667 0.000000 0.976667 ( 0.977630)</pre>
<div class="method-source-code" id="benchmark-source">
<pre><span class="ruby-comment"># File lib/benchmark.rb, line 165</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">benchmark</span>(<span class="ruby-identifier">caption</span> = <span class="ruby-string">""</span>, <span class="ruby-identifier">label_width</span> = <span class="ruby-keyword">nil</span>, <span class="ruby-identifier">format</span> = <span class="ruby-keyword">nil</span>, <span class="ruby-operator">*</span><span class="ruby-identifier">labels</span>) <span class="ruby-comment"># :yield: report</span>
<span class="ruby-identifier">sync</span> = <span class="ruby-constant">STDOUT</span>.<span class="ruby-identifier">sync</span>
<span class="ruby-constant">STDOUT</span>.<span class="ruby-identifier">sync</span> = <span class="ruby-keyword">true</span>
<span class="ruby-identifier">label_width</span> <span class="ruby-operator">||=</span> <span class="ruby-value">0</span>
<span class="ruby-identifier">label_width</span> <span class="ruby-operator">+=</span> <span class="ruby-value">1</span>
<span class="ruby-identifier">format</span> <span class="ruby-operator">||=</span> <span class="ruby-constant">FORMAT</span>
<span class="ruby-identifier">print</span> <span class="ruby-string">' '</span><span class="ruby-operator">*</span><span class="ruby-identifier">label_width</span> <span class="ruby-operator">+</span> <span class="ruby-identifier">caption</span> <span class="ruby-keyword">unless</span> <span class="ruby-identifier">caption</span>.<span class="ruby-identifier">empty?</span>
<span class="ruby-identifier">report</span> = <span class="ruby-constant">Report</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">label_width</span>, <span class="ruby-identifier">format</span>)
<span class="ruby-identifier">results</span> = <span class="ruby-keyword">yield</span>(<span class="ruby-identifier">report</span>)
<span class="ruby-constant">Array</span> <span class="ruby-operator">===</span> <span class="ruby-identifier">results</span> <span class="ruby-keyword">and</span> <span class="ruby-identifier">results</span>.<span class="ruby-identifier">grep</span>(<span class="ruby-constant">Tms</span>).<span class="ruby-identifier">each</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">t</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">print</span>((<span class="ruby-identifier">labels</span>.<span class="ruby-identifier">shift</span> <span class="ruby-operator">||</span> <span class="ruby-identifier">t</span>.<span class="ruby-identifier">label</span> <span class="ruby-operator">||</span> <span class="ruby-string">""</span>).<span class="ruby-identifier">ljust</span>(<span class="ruby-identifier">label_width</span>), <span class="ruby-identifier">t</span>.<span class="ruby-identifier">format</span>(<span class="ruby-identifier">format</span>))
}
<span class="ruby-identifier">report</span>.<span class="ruby-identifier">list</span>
<span class="ruby-keyword">ensure</span>
<span class="ruby-constant">STDOUT</span>.<span class="ruby-identifier">sync</span> = <span class="ruby-identifier">sync</span> <span class="ruby-keyword">unless</span> <span class="ruby-identifier">sync</span>.<span class="ruby-identifier">nil?</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-bm" class="method-detail ">
<div class="method-heading">
<span class="method-name">bm</span><span
class="method-args">(label_width = 0, *labels) { |report| ... }</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>A simple interface to the <a href="Benchmark.html#method-i-benchmark"><code>benchmark</code></a> method, <a href="Benchmark.html#method-i-bm"><code>bm</code></a> generates sequential reports with labels. <code>label_width</code> and <code>labels</code> parameters have the same meaning as for <a href="Benchmark.html#method-i-benchmark"><code>benchmark</code></a>.</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'benchmark'</span>
<span class="ruby-identifier">n</span> = <span class="ruby-value">5000000</span>
<span class="ruby-constant">Benchmark</span>.<span class="ruby-identifier">bm</span>(<span class="ruby-value">7</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">x</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"for:"</span>) { <span class="ruby-keyword">for</span> <span class="ruby-identifier">i</span> <span class="ruby-keyword">in</span> <span class="ruby-value">1</span><span class="ruby-operator">..</span><span class="ruby-identifier">n</span>; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"times:"</span>) { <span class="ruby-identifier">n</span>.<span class="ruby-identifier">times</span> <span class="ruby-keyword">do</span> ; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"upto:"</span>) { <span class="ruby-value">1</span>.<span class="ruby-identifier">upto</span>(<span class="ruby-identifier">n</span>) <span class="ruby-keyword">do</span> ; <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span>; <span class="ruby-keyword">end</span> }
<span class="ruby-keyword">end</span>
</pre>
<p>Generates:</p>
<pre> user system total real
for: 0.960000 0.000000 0.960000 ( 0.957966)
times: 0.960000 0.000000 0.960000 ( 0.960423)
upto: 0.950000 0.000000 0.950000 ( 0.954864)</pre>
<div class="method-source-code" id="bm-source">
<pre><span class="ruby-comment"># File lib/benchmark.rb, line 204</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">bm</span>(<span class="ruby-identifier">label_width</span> = <span class="ruby-value">0</span>, <span class="ruby-operator">*</span><span class="ruby-identifier">labels</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">blk</span>) <span class="ruby-comment"># :yield: report</span>
<span class="ruby-identifier">benchmark</span>(<span class="ruby-constant">CAPTION</span>, <span class="ruby-identifier">label_width</span>, <span class="ruby-constant">FORMAT</span>, <span class="ruby-operator">*</span><span class="ruby-identifier">labels</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">blk</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-bmbm" class="method-detail ">
<div class="method-heading">
<span class="method-name">bmbm</span><span
class="method-args">(width = 0) { |job| ... }</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Sometimes benchmark results are skewed because code executed earlier encounters different garbage collection overheads than that run later. <a href="Benchmark.html#method-i-bmbm"><code>bmbm</code></a> attempts to minimize this effect by running the tests twice, the first time as a rehearsal in order to get the runtime environment stable, the second time for real. <a href="GC.html#method-c-start"><code>GC.start</code></a> is executed before the start of each of the real timings; the cost of this is not included in the timings. In reality, though, there's only so much that <a href="Benchmark.html#method-i-bmbm"><code>bmbm</code></a> can do, and the results are not guaranteed to be isolated from garbage collection and other effects.</p>
<p>Because <a href="Benchmark.html#method-i-bmbm"><code>bmbm</code></a> takes two passes through the tests, it can calculate the required label width.</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'benchmark'</span>
<span class="ruby-identifier">array</span> = (<span class="ruby-value">1</span><span class="ruby-operator">..</span><span class="ruby-value">1000000</span>).<span class="ruby-identifier">map</span> { <span class="ruby-identifier">rand</span> }
<span class="ruby-constant">Benchmark</span>.<span class="ruby-identifier">bmbm</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">x</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"sort!"</span>) { <span class="ruby-identifier">array</span>.<span class="ruby-identifier">dup</span>.<span class="ruby-identifier">sort!</span> }
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">report</span>(<span class="ruby-string">"sort"</span>) { <span class="ruby-identifier">array</span>.<span class="ruby-identifier">dup</span>.<span class="ruby-identifier">sort</span> }
<span class="ruby-keyword">end</span>
</pre>
<p>Generates:</p>
<pre>Rehearsal -----------------------------------------
sort! 1.440000 0.010000 1.450000 ( 1.446833)
sort 1.440000 0.000000 1.440000 ( 1.448257)
-------------------------------- total: 2.890000sec
user system total real
sort! 1.460000 0.000000 1.460000 ( 1.458065)
sort 1.450000 0.000000 1.450000 ( 1.455963)</pre>
<p><a href="Benchmark.html#method-i-bmbm"><code>bmbm</code></a> yields a Benchmark::Job object and returns an array of <a href="Benchmark/Tms.html"><code>Benchmark::Tms</code></a> objects.</p>
<div class="method-source-code" id="bmbm-source">
<pre><span class="ruby-comment"># File lib/benchmark.rb, line 246</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">bmbm</span>(<span class="ruby-identifier">width</span> = <span class="ruby-value">0</span>) <span class="ruby-comment"># :yield: job</span>
<span class="ruby-identifier">job</span> = <span class="ruby-constant">Job</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">width</span>)
<span class="ruby-keyword">yield</span>(<span class="ruby-identifier">job</span>)
<span class="ruby-identifier">width</span> = <span class="ruby-identifier">job</span>.<span class="ruby-identifier">width</span> <span class="ruby-operator">+</span> <span class="ruby-value">1</span>
<span class="ruby-identifier">sync</span> = <span class="ruby-constant">STDOUT</span>.<span class="ruby-identifier">sync</span>
<span class="ruby-constant">STDOUT</span>.<span class="ruby-identifier">sync</span> = <span class="ruby-keyword">true</span>
<span class="ruby-comment"># rehearsal</span>
<span class="ruby-identifier">puts</span> <span class="ruby-string">'Rehearsal '</span>.<span class="ruby-identifier">ljust</span>(<span class="ruby-identifier">width</span><span class="ruby-operator">+</span><span class="ruby-constant">CAPTION</span>.<span class="ruby-identifier">length</span>,<span class="ruby-string">'-'</span>)
<span class="ruby-identifier">ets</span> = <span class="ruby-identifier">job</span>.<span class="ruby-identifier">list</span>.<span class="ruby-identifier">inject</span>(<span class="ruby-constant">Tms</span>.<span class="ruby-identifier">new</span>) { <span class="ruby-operator">|</span><span class="ruby-identifier">sum</span>,(<span class="ruby-identifier">label</span>,<span class="ruby-identifier">item</span>)<span class="ruby-operator">|</span>
<span class="ruby-identifier">print</span> <span class="ruby-identifier">label</span>.<span class="ruby-identifier">ljust</span>(<span class="ruby-identifier">width</span>)
<span class="ruby-identifier">res</span> = <span class="ruby-constant">Benchmark</span>.<span class="ruby-identifier">measure</span>(<span class="ruby-operator">&</span><span class="ruby-identifier">item</span>)
<span class="ruby-identifier">print</span> <span class="ruby-identifier">res</span>.<span class="ruby-identifier">format</span>
<span class="ruby-identifier">sum</span> <span class="ruby-operator">+</span> <span class="ruby-identifier">res</span>
}.<span class="ruby-identifier">format</span>(<span class="ruby-string">"total: %tsec"</span>)
<span class="ruby-identifier">print</span> <span class="ruby-node">" #{ets}\n\n"</span>.<span class="ruby-identifier">rjust</span>(<span class="ruby-identifier">width</span><span class="ruby-operator">+</span><span class="ruby-constant">CAPTION</span>.<span class="ruby-identifier">length</span><span class="ruby-value">+2</span>,<span class="ruby-string">'-'</span>)
<span class="ruby-comment"># take</span>
<span class="ruby-identifier">print</span> <span class="ruby-string">' '</span><span class="ruby-operator">*</span><span class="ruby-identifier">width</span> <span class="ruby-operator">+</span> <span class="ruby-constant">CAPTION</span>
<span class="ruby-identifier">job</span>.<span class="ruby-identifier">list</span>.<span class="ruby-identifier">map</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">label</span>,<span class="ruby-identifier">item</span><span class="ruby-operator">|</span>
<span class="ruby-constant">GC</span>.<span class="ruby-identifier">start</span>
<span class="ruby-identifier">print</span> <span class="ruby-identifier">label</span>.<span class="ruby-identifier">ljust</span>(<span class="ruby-identifier">width</span>)
<span class="ruby-constant">Benchmark</span>.<span class="ruby-identifier">measure</span>(<span class="ruby-identifier">label</span>, <span class="ruby-operator">&</span><span class="ruby-identifier">item</span>).<span class="ruby-identifier">tap</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">res</span><span class="ruby-operator">|</span> <span class="ruby-identifier">print</span> <span class="ruby-identifier">res</span> }
}
<span class="ruby-keyword">ensure</span>
<span class="ruby-constant">STDOUT</span>.<span class="ruby-identifier">sync</span> = <span class="ruby-identifier">sync</span> <span class="ruby-keyword">unless</span> <span class="ruby-identifier">sync</span>.<span class="ruby-identifier">nil?</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-measure" class="method-detail ">
<div class="method-heading">
<span class="method-name">measure</span><span
class="method-args">(label = "") { || ... }</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the time used to execute the given block as a <a href="Benchmark/Tms.html"><code>Benchmark::Tms</code></a> object. Takes <code>label</code> option.</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'benchmark'</span>
<span class="ruby-identifier">n</span> = <span class="ruby-value">1000000</span>
<span class="ruby-identifier">time</span> = <span class="ruby-constant">Benchmark</span>.<span class="ruby-identifier">measure</span> <span class="ruby-keyword">do</span>
<span class="ruby-identifier">n</span>.<span class="ruby-identifier">times</span> { <span class="ruby-identifier">a</span> = <span class="ruby-string">"1"</span> }
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">puts</span> <span class="ruby-identifier">time</span>
</pre>
<p>Generates:</p>
<pre>0.220000 0.000000 0.220000 ( 0.227313)</pre>
<div class="method-source-code" id="measure-source">
<pre><span class="ruby-comment"># File lib/benchmark.rb, line 291</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">measure</span>(<span class="ruby-identifier">label</span> = <span class="ruby-string">""</span>) <span class="ruby-comment"># :yield:</span>
<span class="ruby-identifier">t0</span>, <span class="ruby-identifier">r0</span> = <span class="ruby-constant">Process</span>.<span class="ruby-identifier">times</span>, <span class="ruby-constant">Process</span>.<span class="ruby-identifier">clock_gettime</span>(<span class="ruby-constant">Process</span><span class="ruby-operator">::</span><span class="ruby-constant">CLOCK_MONOTONIC</span>)
<span class="ruby-keyword">yield</span>
<span class="ruby-identifier">t1</span>, <span class="ruby-identifier">r1</span> = <span class="ruby-constant">Process</span>.<span class="ruby-identifier">times</span>, <span class="ruby-constant">Process</span>.<span class="ruby-identifier">clock_gettime</span>(<span class="ruby-constant">Process</span><span class="ruby-operator">::</span><span class="ruby-constant">CLOCK_MONOTONIC</span>)
<span class="ruby-constant">Benchmark</span><span class="ruby-operator">::</span><span class="ruby-constant">Tms</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">t1</span>.<span class="ruby-identifier">utime</span> <span class="ruby-operator">-</span> <span class="ruby-identifier">t0</span>.<span class="ruby-identifier">utime</span>,
<span class="ruby-identifier">t1</span>.<span class="ruby-identifier">stime</span> <span class="ruby-operator">-</span> <span class="ruby-identifier">t0</span>.<span class="ruby-identifier">stime</span>,
<span class="ruby-identifier">t1</span>.<span class="ruby-identifier">cutime</span> <span class="ruby-operator">-</span> <span class="ruby-identifier">t0</span>.<span class="ruby-identifier">cutime</span>,
<span class="ruby-identifier">t1</span>.<span class="ruby-identifier">cstime</span> <span class="ruby-operator">-</span> <span class="ruby-identifier">t0</span>.<span class="ruby-identifier">cstime</span>,
<span class="ruby-identifier">r1</span> <span class="ruby-operator">-</span> <span class="ruby-identifier">r0</span>,
<span class="ruby-identifier">label</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-realtime" class="method-detail ">
<div class="method-heading">
<span class="method-name">realtime</span><span
class="method-args">() { || ... }</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the elapsed real time used to execute the given block.</p>
<div class="method-source-code" id="realtime-source">
<pre><span class="ruby-comment"># File lib/benchmark.rb, line 306</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">realtime</span> <span class="ruby-comment"># :yield:</span>
<span class="ruby-identifier">r0</span> = <span class="ruby-constant">Process</span>.<span class="ruby-identifier">clock_gettime</span>(<span class="ruby-constant">Process</span><span class="ruby-operator">::</span><span class="ruby-constant">CLOCK_MONOTONIC</span>)
<span class="ruby-keyword">yield</span>
<span class="ruby-constant">Process</span>.<span class="ruby-identifier">clock_gettime</span>(<span class="ruby-constant">Process</span><span class="ruby-operator">::</span><span class="ruby-constant">CLOCK_MONOTONIC</span>) <span class="ruby-operator">-</span> <span class="ruby-identifier">r0</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
</section>
</section>
</main>
<footer id="validator-badges" role="contentinfo">
<p><a href="https://validator.w3.org/check/referer">Validate</a>
<p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.2.1.1.
<p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
</footer>