benchmark/README.md

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