diff --git a/benchmark/README.md b/benchmark/README.md new file mode 100644 index 0000000000..695f0eac7f --- /dev/null +++ b/benchmark/README.md @@ -0,0 +1,115 @@ +# Node.js core benchmark tests + +This folder contains benchmark tests to measure the performance for certain +Node.js APIs. + +## How to run tests + +There are two ways to run benchmark tests: + +1. Run all tests of a given type, for example, buffers + +```sh +node benchmark/common.js buffers +``` + +The above command will find all scripts under `buffers` directory and require +each of them as a module. When a test script is required, it creates an instance +of `Benchmark` (a class defined in common.js). In the next tick, the `Benchmark` +constructor iterates through the configuration object property values and run +the test function with each of the combined arguments in spawned processes. For +example, buffers/buffer-read.js has the following configuration: + +```js +var bench = common.createBenchmark(main, { + noAssert: [false, true], + buffer: ['fast', 'slow'], + type: ['UInt8', 'UInt16LE', 'UInt16BE', + 'UInt32LE', 'UInt32BE', + 'Int8', 'Int16LE', 'Int16BE', + 'Int32LE', 'Int32BE', + 'FloatLE', 'FloatBE', + 'DoubleLE', 'DoubleBE'], + millions: [1] +}); +``` +The runner takes one item from each of the property array value to build a list +of arguments to run the main function. The main function will receive the conf +object as follows: + +- first run: +```js + { noAssert: false, + buffer: 'fast', + type: 'UInt8', + millions: 1 + } +``` +- second run: +```js + { + noAssert: false, + buffer: 'fast', + type: 'UInt16LE', + millions: 1 + } +``` +... + +In this case, the main function will run 2*2*14*1 = 56 times. The console output +looks like the following: + +``` +buffers//buffer-read.js +buffers/buffer-read.js noAssert=false buffer=fast type=UInt8 millions=1: 271.83 +buffers/buffer-read.js noAssert=false buffer=fast type=UInt16LE millions=1: 239.43 +buffers/buffer-read.js noAssert=false buffer=fast type=UInt16BE millions=1: 244.57 +... +``` + +2. Run an individual test, for example, buffer-slice.js + +```sh +node benchmark/buffers/buffer-read.js +``` +The output: +``` +buffers/buffer-read.js noAssert=false buffer=fast type=UInt8 millions=1: 246.79 +buffers/buffer-read.js noAssert=false buffer=fast type=UInt16LE millions=1: 240.11 +buffers/buffer-read.js noAssert=false buffer=fast type=UInt16BE millions=1: 245.91 +... +``` + +## How to write a benchmark test + +The benchmark tests are grouped by types. Each type corresponds to a subdirectory, +such as `arrays`, `buffers`, or `fs`. + +Let's add a benchmark test for Buffer.slice function. We first create a file +buffers/buffer-slice.js. + +### The code snippet + +```js +var common = require('../common.js'); // Load the test runner + +var SlowBuffer = require('buffer').SlowBuffer; + +// Create a benchmark test for function `main` and the configuration variants +var bench = common.createBenchmark(main, { + type: ['fast', 'slow'], // Two types of buffer + n: [512] // Number of times (each unit is 1024) to call the slice API +}); + +function main(conf) { + // Read the parameters from the configuration + var n = +conf.n; + var b = conf.type === 'fast' ? buf : slowBuf; + bench.start(); // Start benchmarking + for (var i = 0; i < n * 1024; i++) { + // Add your test here + b.slice(10, 256); + } + bench.end(n); // End benchmarking +} +```