Skip to content

Commit

Permalink
doc: warn against streaming from character devices
Browse files Browse the repository at this point in the history
charcter device streaming works just like any other streams, but hangs
on the close callsite due to the worker thread being blocked on the read
and main thread waiting for any async event that may not occur.

Document this behavior and suggest a potential workaround.

Fixes: nodejs#15439
  • Loading branch information
gireeshpunathil committed Aug 14, 2018
1 parent 4ce744a commit 4dfe0b3
Showing 1 changed file with 20 additions and 0 deletions.
20 changes: 20 additions & 0 deletions doc/api/fs.md
Original file line number Diff line number Diff line change
Expand Up @@ -1464,6 +1464,26 @@ the specified file descriptor. This means that no `'open'` event will be
emitted. `fd` should be blocking; non-blocking `fd`s should be passed to
[`net.Socket`][].

Also note that the blocking fd, if pointing to a character device (such as
keyboard or sound card) can potentially block the main thread on stream close.
This is because these devices do not produce EOF character as part of their data
flow cycle, and thereby exemplify endless streams. As a result, they do not
respond to `stream.close()` call. A workaround is to close the stream first
using `stream.close()` and then push a random character into the stream, issue
a single read. This unblocks the reader thread, leads to the completion of the
data flow cycle, and the actual closing of the stream.

```js
const fs = require('fs');
// Create a stream from some character device.
const stream = fs.createReadStream('/dev/input/event0');
setTimeout(() => {
stream.close(); // This does not close the stream.
stream.push(null);
stream.read(0); // Pushing a null and reading leads to close.
}, 100);
```

If `autoClose` is false, then the file descriptor won't be closed, even if
there's an error. It is the application's responsibility to close it and make
sure there's no file descriptor leak. If `autoClose` is set to true (default
Expand Down

0 comments on commit 4dfe0b3

Please sign in to comment.