@@ -3156,6 +3156,28 @@ system requests but rather the internal buffering `fs.readFile` performs. |
3156 | 3156 | the call to `fs.readFile()` with the same file descriptor, would give |
3157 | 3157 | `'World'`, rather than `'Hello World'`. |
3158 | 3158 |
|
| 3159 | +### Performance Considerations |
| 3160 | + |
| 3161 | +The `fs.readFile()` method asynchronously reads the contents of a file into |
| 3162 | +memory one chunk at a time, allowing the event loop to turn between each chunk. |
| 3163 | +This allows the read operation to have less impact on other activity that may |
| 3164 | +be using the underlying libuv thread pool but means that it will take longer |
| 3165 | +to read a complete file into memory. |
| 3166 | + |
| 3167 | +The additional read overhead can vary broadly on different systems and depends |
| 3168 | +on the type of file being read. If the file type is not a regular file (a pipe |
| 3169 | +for instance) and Node.js is unable to determine an actual file size, each read |
| 3170 | +operation will load on 64kb of data. For regular files, each read will process |
| 3171 | +512kb of data. |
| 3172 | + |
| 3173 | +For applications that require as-fast-as-possible reading of file contents, it |
| 3174 | +is better to use `fs.read()` directly and for application code to manage |
| 3175 | +reading the full contents of the file itself. |
| 3176 | + |
| 3177 | +The Node.js GitHub issue [#25741][] provides more information and a detailed |
| 3178 | +analysis on the performance of `fs.readFile()` for multiple file sizes in |
| 3179 | +different Node.js versions. |
| 3180 | + |
3159 | 3181 | ## `fs.readFileSync(path[, options])` |
3160 | 3182 | <!-- YAML |
3161 | 3183 | added: v0.1.8 |
@@ -6212,6 +6234,7 @@ through `fs.open()` or `fs.writeFile()` or `fsPromises.open()`) will fail with |
6212 | 6234 | A call to `fs.ftruncate()` or `filehandle.truncate()` can be used to reset |
6213 | 6235 | the file contents. |
6214 | 6236 |
|
| 6237 | +[#25741]: https://github.com/nodejs/node/issues/25741 |
6215 | 6238 | [Caveats]: #fs_caveats |
6216 | 6239 | [Common System Errors]: errors.md#errors_common_system_errors |
6217 | 6240 | [FS constants]: #fs_fs_constants_1 |
|