Skip to content

Commit bfdb28e

Browse files
addaleaxtargos
authored andcommitted
doc: fix up warning text about character devices
The text contained a number of inaccuracies: - The main thread is never blocked by a stream close. - There is no such thing as an EOF character on the OS level, the libuv level, or the Node.js stream level. - These streams *do* respond to `.close()`, but pending reads can delay this indefinitely. - Pushing a random character into the stream works only when the source data can be controlled; Using the JS `.push()` method is something different, and does not “unblock” any threads. Refs: #21212 PR-URL: #22569 Reviewed-By: Gireesh Punathil <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]>
1 parent 6737201 commit bfdb28e

File tree

1 file changed

+11
-10
lines changed

1 file changed

+11
-10
lines changed

doc/api/fs.md

+11-10
Original file line numberDiff line numberDiff line change
@@ -1449,23 +1449,24 @@ the specified file descriptor. This means that no `'open'` event will be
14491449
emitted. `fd` should be blocking; non-blocking `fd`s should be passed to
14501450
[`net.Socket`][].
14511451

1452-
The blocking `fd`, if pointing to a character device (such as keyboard or
1453-
sound card) can potentially block the main thread on stream close. This is
1454-
because these devices do not produce EOF character as part of their data
1455-
flow cycle, and thereby exemplify endless streams. As a result, they do not
1456-
respond to `stream.close()`. A workaround is to close the stream first
1457-
using `stream.close()` and then push a random character into the stream, and
1458-
issue a single read. This unblocks the reader thread, leads to the completion
1459-
of the data flow cycle, and the actual closing of the stream.
1452+
If `fd` points to a character device that only supports blocking reads
1453+
(such as keyboard or sound card), read operations do not finish until data is
1454+
available. This can prevent the process from exiting and the stream from
1455+
closing naturally.
14601456

14611457
```js
14621458
const fs = require('fs');
14631459
// Create a stream from some character device.
14641460
const stream = fs.createReadStream('/dev/input/event0');
14651461
setTimeout(() => {
1466-
stream.close(); // This does not close the stream.
1462+
stream.close(); // This may not close the stream.
1463+
// Artificially marking end-of-stream, as if the underlying resource had
1464+
// indicated end-of-file by itself, allows the stream to close.
1465+
// This does not cancel pending read operations, and if there is such an
1466+
// operation, the process may still not be able to exit successfully
1467+
// until it finishes.
14671468
stream.push(null);
1468-
stream.read(0); // Pushing a null and reading leads to close.
1469+
stream.read(0);
14691470
}, 100);
14701471
```
14711472

0 commit comments

Comments
 (0)