From 20fa30c871bc4a14cf8dc133302f877bcfae8d86 Mon Sep 17 00:00:00 2001 From: JialuZhang-intel Date: Fri, 17 Jun 2022 16:47:22 +0800 Subject: [PATCH] doc: add new useful V8 option Add the `--max_semi_space_size` flag into useful V8 option. Fixes: https://github.com/nodejs/node/issues/42511 PR-URL: https://github.com/nodejs/node/pull/42575 Reviewed-By: Ben Noordhuis Reviewed-By: James M Snell Reviewed-By: Michael Dawson --- doc/api/cli.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/doc/api/cli.md b/doc/api/cli.md index b9d63b08aa4a28..b46469fc0a0788 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -2013,6 +2013,32 @@ On a machine with 2 GiB of memory, consider setting this to $ node --max-old-space-size=1536 index.js ``` +### `--max-semi-space-size=SIZE` (in megabytes) + +Sets the maximum [semi-space][] size for V8's [scavenge garbage collector][] in +MiB (megabytes). +Increasing the max size of a semi-space may improve throughput for Node.js at +the cost of more memory consumption. + +Since the young generation size of the V8 heap is three times (see +[`YoungGenerationSizeFromSemiSpaceSize`][] in V8) the size of the semi-space, +an increase of 1 MiB to semi-space applies to each of the three individual +semi-spaces and causes the heap size to increase by 3 MiB. The throughput +improvement depends on your workload (see [#42511][]). + +The default value is 16 MiB for 64-bit systems and 8 MiB for 32-bit systems. To +get the best configuration for your application, you should try different +max-semi-space-size values when running benchmarks for your application. + +For example, benchmark on a 64-bit systems: + +```bash +for MiB in 16 32 64 128; do + node --max-semi-space-size=$MiB index.js +done +``` + +[#42511]: https://github.com/nodejs/node/issues/42511 [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/ [CommonJS]: modules.md [ECMAScript module loader]: esm.md#loaders @@ -2038,6 +2064,7 @@ $ node --max-old-space-size=1536 index.js [`NODE_OPTIONS`]: #node_optionsoptions [`NO_COLOR`]: https://no-color.org [`SlowBuffer`]: buffer.md#class-slowbuffer +[`YoungGenerationSizeFromSemiSpaceSize`]: https://chromium.googlesource.com/v8/v8.git/+/refs/tags/10.3.129/src/heap/heap.cc#328 [`dns.lookup()`]: dns.md#dnslookuphostname-options-callback [`dns.setDefaultResultOrder()`]: dns.md#dnssetdefaultresultorderorder [`dnsPromises.lookup()`]: dns.md#dnspromiseslookuphostname-options @@ -2057,6 +2084,8 @@ $ node --max-old-space-size=1536 index.js [libuv threadpool documentation]: https://docs.libuv.org/en/latest/threadpool.html [remote code execution]: https://www.owasp.org/index.php/Code_Injection [running tests from the command line]: test.md#running-tests-from-the-command-line +[scavenge garbage collector]: https://v8.dev/blog/orinoco-parallel-scavenger [security warning]: #warning-binding-inspector-to-a-public-ipport-combination-is-insecure +[semi-space]: https://www.memorymanagement.org/glossary/s.html#semi.space [timezone IDs]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones [ways that `TZ` is handled in other environments]: https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html