From 92d731dec9b5298978f96b9806fcf8414fa72a59 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Mon, 11 Jan 2021 12:06:30 -0800
Subject: [PATCH] doc: add performance notes for fs.readFile

Issue https://github.com/nodejs/node/issues/25741 discusses a number of
performance considerations for fs.readFile, which was changed in Node.js
10.x to split discreet chunk reads over multiple event loop turns. While
the fs.readFile() operation is certainly slower than it was pre 10.x,
it's unlikely to be faster. Document the performance consideration and
link back to the issue for more in depth analysis.

Signed-off-by: James M Snell <jasnell@gmail.com>
Fixes: https://github.com/nodejs/node/issues/25741
---
 doc/api/fs.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 8f896437d7438d..e528c292a43a66 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -3162,6 +3162,28 @@ system requests but rather the internal buffering `fs.readFile` performs.
    the call to `fs.readFile()` with the same file descriptor, would give
    `'World'`, rather than `'Hello World'`.
 
+### Performance Considerations
+
+The `fs.readFile()` method asynchronously reads the contents of a file into
+memory one chunk at a time, allowing the event loop to turn between each chunk.
+This allows the read operation to have less impact on other activity that may
+be using the underlying libuv thread pool but means that it will take longer
+to read a complete file into memory.
+
+The additional read overhead can vary broadly on different systems and depends
+on the type of file being read. If the file type is not a regular file (a pipe
+for instance) and Node.js is unable to determine an actual file size, each read
+operation will load on 64kb of data. For regular files, each read will process
+512kb of data.
+
+For applications that require as-fast-as-possible reading of file contents, it
+is better to use `fs.read()` directly and for application code to manage
+reading the full contents of the file itself.
+
+The Node.js GitHub issue [#25741][] provides more information and a detailed
+analysis on the performance of `fs.readFile()` for multiple file sizes in
+different Node.js versions.
+
 ## `fs.readFileSync(path[, options])`
 <!-- YAML
 added: v0.1.8
@@ -6214,6 +6236,7 @@ through `fs.open()` or `fs.writeFile()` or `fsPromises.open()`) will fail with
 A call to `fs.ftruncate()` or `filehandle.truncate()` can be used to reset
 the file contents.
 
+[#25741]: https://github.com/nodejs/node/issues/25741
 [Caveats]: #fs_caveats
 [Common System Errors]: errors.md#errors_common_system_errors
 [FS constants]: #fs_fs_constants_1