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 ## How to run tests
   7
   8 There are two ways to run benchmark tests:
   9
  10 1. Run all tests of a given type, for example, buffers
  11
  12 ```sh
  13 node benchmark/common.js buffers
  14 ```
  15
  16 The above command will find all scripts under `buffers` directory and require
  17 each of them as a module. When a test script is required, it creates an instance
  18 of `Benchmark` (a class defined in common.js). In the next tick, the `Benchmark`
  19 constructor iterates through the configuration object property values and run
  20 the test function with each of the combined arguments in spawned processes. For
  21 example, buffers/buffer-read.js has the following configuration:
  22
  23 ```js
  24 var bench = common.createBenchmark(main, {
  25     noAssert: [false, true],
  26     buffer: ['fast', 'slow'],
  27     type: ['UInt8', 'UInt16LE', 'UInt16BE',
  28         'UInt32LE', 'UInt32BE',
  29         'Int8', 'Int16LE', 'Int16BE',
  30         'Int32LE', 'Int32BE',
  31         'FloatLE', 'FloatBE',
  32         'DoubleLE', 'DoubleBE'],
  33         millions: [1]
  34 });
  35 ```
  36 The runner takes one item from each of the property array value to build a list
  37 of arguments to run the main function. The main function will receive the conf
  38 object as follows:
  39
  40 - first run:
  41 ```js
  42     {   noAssert: false,
  43         buffer: 'fast',
  44         type: 'UInt8',
  45         millions: 1
  46     }
  47 ```
  48 - second run:
  49 ```js
  50     {
  51         noAssert: false,
  52         buffer: 'fast',
  53         type: 'UInt16LE',
  54         millions: 1
  55     }
  56 ```
  57 ...
  58
  59 In this case, the main function will run 2*2*14*1 = 56 times. The console output
  60 looks like the following:
  61
  62 ```
  63 buffers//buffer-read.js
  64 buffers/buffer-read.js noAssert=false buffer=fast type=UInt8 millions=1: 271.83
  65 buffers/buffer-read.js noAssert=false buffer=fast type=UInt16LE millions=1: 239.43
  66 buffers/buffer-read.js noAssert=false buffer=fast type=UInt16BE millions=1: 244.57
  67 ...
  68 ```
  69
  70 2. Run an individual test, for example, buffer-slice.js
  71
  72 ```sh
  73 node benchmark/buffers/buffer-read.js
  74 ```
  75 The output:
  76 ```
  77 buffers/buffer-read.js noAssert=false buffer=fast type=UInt8 millions=1: 246.79
  78 buffers/buffer-read.js noAssert=false buffer=fast type=UInt16LE millions=1: 240.11
  79 buffers/buffer-read.js noAssert=false buffer=fast type=UInt16BE millions=1: 245.91
  80 ...
  81 ```
  82
  83 ## How to write a benchmark test
  84
  85 The benchmark tests are grouped by types. Each type corresponds to a subdirectory,
  86 such as `arrays`, `buffers`, or `fs`.
  87
  88 Let's add a benchmark test for Buffer.slice function. We first create a file
  89 buffers/buffer-slice.js.
  90
  91 ### The code snippet
  92
  93 ```js
  94 var common = require('../common.js'); // Load the test runner
  95
  96 var SlowBuffer = require('buffer').SlowBuffer;
  97
  98 // Create a benchmark test for function `main` and the configuration variants
  99 var bench = common.createBenchmark(main, {
 100   type: ['fast', 'slow'], // Two types of buffer
 101   n: [512] // Number of times (each unit is 1024) to call the slice API
 102 });
 103
 104 function main(conf) {
 105   // Read the parameters from the configuration
 106   var n = +conf.n;
 107   var b = conf.type === 'fast' ? buf : slowBuf;
 108   bench.start(); // Start benchmarking
 109   for (var i = 0; i < n * 1024; i++) {
 110     // Add your test here
 111     b.slice(10, 256);
 112   }
 113   bench.end(n); // End benchmarking
 114 }
 115 ```