README.md
1# Node.js Core Benchmarks
2
3This folder contains code and data used to measure performance
4of different Node.js implementations and different ways of
5writing JavaScript run by the built-in JavaScript engine.
6
7For a detailed guide on how to write and run benchmarks in this
8directory, see [the guide on benchmarks](../doc/guides/writing-and-running-benchmarks.md).
9
10## Table of Contents
11
12* [Benchmark directories](#benchmark-directories)
13* [Common API](#common-api)
14
15## Benchmark Directories
16
17| Directory | Purpose |
18| --------------- | ---------------------------------------------------------------------------------------------------------------- |
19| assert | Benchmarks for the `assert` subsystem. |
20| buffers | Benchmarks for the `buffer` subsystem. |
21| child\_process | Benchmarks for the `child_process` subsystem. |
22| crypto | Benchmarks for the `crypto` subsystem. |
23| dgram | Benchmarks for the `dgram` subsystem. |
24| domain | Benchmarks for the `domain` subsystem. |
25| es | Benchmarks for various new ECMAScript features and their pre-ES2015 counterparts. |
26| events | Benchmarks for the `events` subsystem. |
27| fixtures | Benchmarks fixtures used in various benchmarks throughout the benchmark suite. |
28| fs | Benchmarks for the `fs` subsystem. |
29| http | Benchmarks for the `http` subsystem. |
30| http2 | Benchmarks for the `http2` subsystem. |
31| misc | Miscellaneous benchmarks and benchmarks for shared internal modules. |
32| module | Benchmarks for the `module` subsystem. |
33| net | Benchmarks for the `net` subsystem. |
34| path | Benchmarks for the `path` subsystem. |
35| perf_hooks | Benchmarks for the `perf_hooks` subsystem. |
36| process | Benchmarks for the `process` subsystem. |
37| querystring | Benchmarks for the `querystring` subsystem. |
38| streams | Benchmarks for the `streams` subsystem. |
39| string\_decoder | Benchmarks for the `string_decoder` subsystem. |
40| timers | Benchmarks for the `timers` subsystem, including `setTimeout`, `setInterval`, .etc. |
41| tls | Benchmarks for the `tls` subsystem. |
42| url | Benchmarks for the `url` subsystem, including the legacy `url` implementation and the WHATWG URL implementation. |
43| util | Benchmarks for the `util` subsystem. |
44| vm | Benchmarks for the `vm` subsystem. |
45
46### Other Top-level files
47
48The top-level files include common dependencies of the benchmarks
49and the tools for launching benchmarks and visualizing their output.
50The actual benchmark scripts should be placed in their corresponding
51directories.
52
53* `_benchmark_progress.js`: implements the progress bar displayed
54 when running `compare.js`
55* `_cli.js`: parses the command line arguments passed to `compare.js`,
56 `run.js` and `scatter.js`
57* `_cli.R`: parses the command line arguments passed to `compare.R`
58* `_http-benchmarkers.js`: selects and runs external tools for benchmarking
59 the `http` subsystem.
60* `common.js`: see [Common API](#common-api).
61* `compare.js`: command line tool for comparing performance between different
62 Node.js binaries.
63* `compare.R`: R script for statistically analyzing the output of
64 `compare.js`
65* `run.js`: command line tool for running individual benchmark suite(s).
66* `scatter.js`: command line tool for comparing the performance
67 between different parameters in benchmark configurations,
68 for example to analyze the time complexity.
69* `scatter.R`: R script for visualizing the output of `scatter.js` with
70 scatter plots.
71
72## Common API
73
74The common.js module is used by benchmarks for consistency across repeated
75tasks. It has a number of helpful functions and properties to help with
76writing benchmarks.
77
78### `createBenchmark(fn, configs[, options])`
79
80See [the guide on writing benchmarks](../doc/guides/writing-and-running-benchmarks.md#basics-of-a-benchmark).
81
82### `default_http_benchmarker`
83
84The default benchmarker used to run HTTP benchmarks.
85See [the guide on writing HTTP benchmarks](../doc/guides/writing-and-running-benchmarks.md#creating-an-http-benchmark).
86
87### `PORT`
88
89The default port used to run HTTP benchmarks.
90See [the guide on writing HTTP benchmarks](../doc/guides/writing-and-running-benchmarks.md#creating-an-http-benchmark).
91
92### `sendResult(data)`
93
94Used in special benchmarks that can't use `createBenchmark` and the object
95it returns to accomplish what they need. This function reports timing
96data to the parent process (usually created by running `compare.js`, `run.js` or
97`scatter.js`).
98