Add `signal.get_wakeup_fd()`

Feature or enhancement

Proposal:

We have signal.set_wakeup_fd(), which sets a new file descriptor and returns the old one. However, there are at least three cases where we want to get the current wakeup fd without setting a new one:

1. Obtaining debug information about the current state of the process, which also applies to tests (how can we ensure that a particular function actually sets the wakeup fd?).
2. Raising warnings if it has been changed (reset to -1?) in some scope we are considering.
3. Conditionally setting the wakeup fd depending on whether it has been changed in another scope.

The reason I opened this issue relates to the third case. I have an "inner" wakeup fd (guest) and an "outer" wakeup fd (host). When the outer wakeup fd is either not set (equal to -1) or equal to the inner wakeup fd, it is updated along with the inner one. In this case:

• If I do not set/get wakeup fd, I will not know the current inner wakeup fd, and as a result, I will not be able to perform checks.
• If I always set the outer wakeup fd when exiting the inner scope, then in case of equality, this may happen when the wakeup fd has already been closed (and reset to -1) in the inner scope, which in turn will lead to either an OSError or a possible write to a false file descriptor (since file descriptors are reusable).
• I also cannot set the inner wakeup fd, since it could have been updated in the inner scope.
• The code in the inner scope is not under my control.

The simplest implementation of signal.get_wakeup_fd() at the Python level looks like this:

import signal

def get_wakeup_fd():
    fd = signal.set_wakeup_fd(-1)

    signal.set_wakeup_fd(fd)

    return fd

However, it has two drawbacks:

1. We lose the current value of the warn_on_full_buffer parameter.
2. There is a race condition between the two signal.set_wakeup_fd() calls (what if a signal is sent to the process during this time?), which can lead to lost signals (and thus the guest not waking up).

To solve the race condition problem, we would have to create our own wakeup pair, for example in the form of a non-blocking pipe, and send signals from the pipe to the current wakeup fd, effectively emulating the trip_signal() function. But this only sounds simple on Unix. On Windows:

1. It is not possible to create a non-blocking pipe using the public API without ctypes until Python 3.12. The closest alternative using the private API would look like this:

   from _winapi import SetNamedPipeHandleState
   from msvcrt import get_osfhandle
   
   def set_blocking(pipefd, blocking, /):
       SetNamedPipeHandleState(
           get_osfhandle(pipefd),
           0 if blocking else 1,
           None,
           None,
       )
   

2. We cannot use os.write() if the wakeup fd is a socket. In this case, we would either have to try to handle sockets via socket.fromfd(), or use an alternative approach with signal.signal()+signal.raise_signal() (disable the current signal handlers, implicitly call trip_signal() by resending signals to the current process, enable them back), but the latter is even more non-trivial and is unlikely to have a correct solution.

Meanwhile, at the signalmodule.c level, to get the current wakeup fd, it is enough to just get wakeup.fd. So why not add the corresponding function?

import signal

fd = signal.get_wakeup_fd()

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Linked PRs

• gh-145726

Start in Modules/signalmodule.c, especially the wakeup.fd state and the trip_signal() path linked in the issue. Review the existing signal.set_wakeup_fd() behavior and its documentation, then inspect the linked PR gh-145726 before starting. Done means the current wakeup fd can be retrieved without the race or warn_on_full_buffer limitations described here, with behavior covered across the relevant platforms.