doc: explain process.stdout in worker_threads

[HarshithaKP]

fixes: #28386

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

[addaleax]

This is not accurate:

> void new Worker(`console.log('isatty(1)', require('tty').isatty(1))`, {eval:true})
undefined
> isatty(1) true

tty.isatty() is generally not concerned with what thread it’s being called on, as fds are a process-wide resource.

[HarshithaKP]

@addaleax , I am describing fd 1, instead process.stdout.fd

void new Worker(`console.log('isatty(process.stdout.fd)', require('tty').isatty(process.stdout.fd))`, {eval:true})
undefined
satty(process.stdout.fd) false

[HarshithaKP]

Edit: I am describing fd 1 -> I am NOT describing fd 1

[Trott]

process.stdout.fd is undefined in a worker thread. (Should it be?)

> void new Worker('console.log("fd:", process.stdout.fd)', {eval: true})
undefined
> fd: undefined

[Trott]

@HarshithaKP Feel free to re-open (or request that it be re-opened if the interface won't let you do it) if you plan on continuing to work on this. It seems to me that the proper place for the documentation would be inside the worker_threads documentation and/or in process documentation.

[HarshithaKP]

@Trott , why did you close this ?

This API (isatty) exhibits uncommon behaviour in certain contexts and that's what I am documenting. According to me such document should be near the API itself.

[Trott]

@Trott , why did you close this ?

Because this doesn't seem like the right approach and I thought (wrongly?) that seemed to be pretty clear. (We have over 200 open PRs so I also thought maybe it's not a bad thing to be a little more efficient about closing ones that may be stalled. They're easy enough to re-open.)

This API (isatty) exhibits uncommon behaviour in certain contexts

I don't think it exhibits uncommon behavior. If process.stdout.fd is undefined, then isatty(process.stdout.fd) should return false. Which is what it does. Unless I'm missing something (and I may indeed be missing something important), the issue here isn't anything unusual happening with isatty(). The issue is that process.stdout.fd in a worker thread may not be what a user assumes/expects. But that should be documented in the process and/or worker_thread documentation. I suppose a carefully-worded and thoughtfully-placed note about this might not be entirely out-of-place in the isatty() docs. But that sort of thing can get out of hand quickly. We don't want to include a note about this in every API that takes an fd.

[Trott]

The issue is that process.stdout.fd in a worker thread may not be what a user assumes/expects.

And now that I think more about it, is that a bug?

[Trott]

So, to summarize:

In a main thread, process.stdout.fd is (usually) 1.

In a worker thread, process.stdout.fd will (usually) be undefined.

Which leads us to the questions:

• process.stdout.fd is not defined in the docs (as far I know, at least). Therefore, should users be able to rely on it?

• Is the missing process.stdout.fd in worker threads a bug? Should process.stdout.fd be 1 by default?

[HarshithaKP]

@Trott ,

But that sort of thing can get out of hand quickly. We don’t want to include a note about this in every API that takes an fd.

acknowledged.

Which leads us to the questions

I don't know. cc @addaleax

[Trott]

Separate issue: The isatty() doc says that fd must be a number and indicates it is required. This issue here shows that is not accurate. Perhaps we need to update the docs saying that certain (all?) non-number values will be coerced (if that's true) to a number?

[Trott]

Perhaps we need to update the docs saying that certain (all?) non-number values will be coerced (if that's true) to a number?

Looks like it does not coerce and simply returns false. (Only messed around a little in the REPL, didn't look at the code so I could still be wrong.) Whatever the actual case it, it should be documented, I imagine.

[addaleax]

• process.stdout.fd is not defined in the docs (as far I know, at least). Therefore, should users be able to rely on it?

Yes. I think there’s an open issue about documenting these, and removing them is not a viable option at any point in Node’s future anyway, I imagine.

• Is the missing process.stdout.fd in worker threads a bug? Should process.stdout.fd be 1 by default?

No. process.stdout in worker threads is not associated with a file descriptor. The .fd property should be undefined.

[HarshithaKP]

@addaleax and @Trott , That essentially boils down to documenting process.stdout.fd and its status in worker threads, leaving the doc for this api(isatty) as is. Please let me know.
And if so can I do it in this PR itself ?

[addaleax]

@HarshithaKP I’d open a new PR, since it”s unrelated to the contents of this PR.

[HarshithaKP]

Closing this as this is unrelated to the contents of PR.