os/signal: documentation clarification

[withinboredom]

Go version

1.23

Output of go env in your module/workspace:

N/A

What did you do?

The current documentation reads:

The non-Go code should not change the signal mask on any threads created by the Go runtime. If the non-Go code starts new threads of its own, it may set the signal mask as it pleases.

But it doesn't state the consequences for doing so or in what conditions it is safe to do so. For example:

func callC() {
  runtime.LockOSThread()
  C.methodThatEventuallyCallsBackToGo()
}

// later
go callC()

What exactly would happen to signal masks in this case? Further, is the documentation saying that only if non-go code starts threads, it can set the signal mask, or is it saying that only the children may set signal masks?

What did you see happen?

Confusing or missing documentation in regards to signal masks.

What did you expect to see?

More detail and clarification in regards to signal masks in non-go code.

[ianlancetaylor]

I don't think the docs should lock us into specific consequences. I'll change them to read

The non-Go code should not change the signal mask on any threads created by the Go runtime. If the non-Go code starts new threads itself, those threads may set the signal mask as they please.

[gopherbot]

Change https://go.dev/cl/589755 mentions this issue: os/signal: clarify that non-Go thread may change signal mask

[withinboredom]

Thank you for the clarification @ianlancetaylor! That's really all I needed to know!