1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: add performance notes for fs.readFile

Browse Source 
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

PR-URL: https://github.com/nodejs/node/pull/36880
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
This commit is contained in:
James M Snell 2021-01-11 12:06:30 -08:00
parent 88153dc175
commit 408e9d3a3a
No known key found for this signature in database
GPG Key ID: 7341B15C070877AC
1 changed files with 23 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
doc/api/fs.md
View File

@ -3166,6 +3166,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
@ -6222,6 +6244,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