Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add performance notes for fs.readFile #36880

Closed
wants to merge 1 commit into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
23 changes: 23 additions & 0 deletions doc/api/fs.md
Expand Up @@ -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.

jasnell marked this conversation as resolved.
Show resolved Hide resolved
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
Expand Down Expand Up @@ -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
Expand Down