benchmark/README.md

   1 # io.js core benchmark tests
   2
   3 This folder contains benchmark tests to measure the performance for certain
   4 io.js APIs.
   5
   6 ## Prerequisites
   7
   8 Most of the http benchmarks require [`wrk`][wrk] and [`ab`][ab] being installed.
   9 These are most often available through your preferred package manager.
  10
  11 [wrk]: https://github.com/wg/wrk
  12 [ab]: http://httpd.apache.org/docs/2.2/programs/ab.html
  13
  14 ## How to run tests
  15
  16 There are two ways to run benchmark tests:
  17
  18 1. Run all tests of a given type, for example, buffers
  19
  20 ```sh
  21 iojs benchmark/common.js buffers
  22 ```
  23
  24 The above command will find all scripts under `buffers` directory and require
  25 each of them as a module. When a test script is required, it creates an instance
  26 of `Benchmark` (a class defined in common.js). In the next tick, the `Benchmark`
  27 constructor iterates through the configuration object property values and run
  28 the test function with each of the combined arguments in spawned processes. For
  29 example, buffers/buffer-read.js has the following configuration:
  30
  31 ```js
  32 var bench = common.createBenchmark(main, {
  33     noAssert: [false, true],
  34     buffer: ['fast', 'slow'],
  35     type: ['UInt8', 'UInt16LE', 'UInt16BE',
  36         'UInt32LE', 'UInt32BE',
  37         'Int8', 'Int16LE', 'Int16BE',
  38         'Int32LE', 'Int32BE',
  39         'FloatLE', 'FloatBE',
  40         'DoubleLE', 'DoubleBE'],
  41         millions: [1]
  42 });
  43 ```
  44 The runner takes one item from each of the property array value to build a list
  45 of arguments to run the main function. The main function will receive the conf
  46 object as follows:
  47
  48 - first run:
  49 ```js
  50     {   noAssert: false,
  51         buffer: 'fast',
  52         type: 'UInt8',
  53         millions: 1
  54     }
  55 ```
  56 - second run:
  57 ```js
  58     {
  59         noAssert: false,
  60         buffer: 'fast',
  61         type: 'UInt16LE',
  62         millions: 1
  63     }
  64 ```
  65 ...
  66
  67 In this case, the main function will run 2*2*14*1 = 56 times. The console output
  68 looks like the following:
  69
  70 ```
  71 buffers//buffer-read.js
  72 buffers/buffer-read.js noAssert=false buffer=fast type=UInt8 millions=1: 271.83
  73 buffers/buffer-read.js noAssert=false buffer=fast type=UInt16LE millions=1: 239.43
  74 buffers/buffer-read.js noAssert=false buffer=fast type=UInt16BE millions=1: 244.57
  75 ...
  76 ```
  77
  78 2. Run an individual test, for example, buffer-slice.js
  79
  80 ```sh
  81 iojs benchmark/buffers/buffer-read.js
  82 ```
  83 The output:
  84 ```
  85 buffers/buffer-read.js noAssert=false buffer=fast type=UInt8 millions=1: 246.79
  86 buffers/buffer-read.js noAssert=false buffer=fast type=UInt16LE millions=1: 240.11
  87 buffers/buffer-read.js noAssert=false buffer=fast type=UInt16BE millions=1: 245.91
  88 ...
  89 ```
  90
  91 3. Run tests with options
  92
  93 This example will run only the first type of url test, with one iteration.
  94 (Note: benchmarks require __many__ iterations to be statistically accurate.)
  95
  96
  97 ```sh
  98 iojs benchmark/url/url-parse.js type=one n=1
  99 ```
 100 Output:
 101 ```
 102 url/url-parse.js type=one n=1: 1663.74402
 103 ```
 104
 105 ## How to write a benchmark test
 106
 107 The benchmark tests are grouped by types. Each type corresponds to a subdirectory,
 108 such as `arrays`, `buffers`, or `fs`.
 109
 110 Let's add a benchmark test for Buffer.slice function. We first create a file
 111 buffers/buffer-slice.js.
 112
 113 ### The code snippet
 114
 115 ```js
 116 var common = require('../common.js'); // Load the test runner
 117
 118 var SlowBuffer = require('buffer').SlowBuffer;
 119
 120 // Create a benchmark test for function `main` and the configuration variants
 121 var bench = common.createBenchmark(main, {
 122   type: ['fast', 'slow'], // Two types of buffer
 123   n: [512] // Number of times (each unit is 1024) to call the slice API
 124 });
 125
 126 function main(conf) {
 127   // Read the parameters from the configuration
 128   var n = +conf.n;
 129   var b = conf.type === 'fast' ? buf : slowBuf;
 130   bench.start(); // Start benchmarking
 131   for (var i = 0; i < n * 1024; i++) {
 132     // Add your test here
 133     b.slice(10, 256);
 134   }
 135   bench.end(n); // End benchmarking
 136 }
 137 ```