Add `signal.get_wakeup_fd()`

[x42005e1f]

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-145638: Add signal.get_wakeup_fd() #145726

[anand-official]

This is a well-motivated feature request. The use case for querying the wakeup fd without side effects is clear, especially for nested signal handling contexts.

Implementation Approach

The C-level implementation would be straightforward in Modules/signalmodule.c:

static PyObject *
signal_get_wakeup_fd(PyObject *self, PyObject *Py_UNUSED(ignored))
{
    return PyLong_FromLong(wakeup.fd);
}

This avoids both problems you mentioned:

1. No race condition between two set_wakeup_fd() calls
2. Preserves the warn_on_full_buffer state

API Considerations

Should get_wakeup_fd() also return the warn_on_full_buffer state? Options:

Option 1: Just return fd (simple)

fd = signal.get_wakeup_fd()  # returns int

Option 2: Return tuple with both values (more complete)

fd, warn_on_full = signal.get_wakeup_fd()  # returns (int, bool)

Option 2 would be more symmetric with set_wakeup_fd(fd, *, warn_on_full_buffer=True) and allow full state inspection, but breaks the simple int return type convention.

Thread Safety

Since wakeup.fd is only modified/read in the main thread (enforced by set_wakeup_fd), the getter would have the same thread safety guarantees as the setter.

Would you like me to draft a PR implementing this? I'd lean toward Option 1 for simplicity unless there's a strong need for inspecting warn_on_full_buffer.

[picnixz]

@anand-official Please avoid posting LLM-generated answers without reviewing them and curating them. There are un-necessary parts. And read https://devguide.python.org/getting-started/generative-ai/.

[x42005e1f]

Should get_wakeup_fd() also return the warn_on_full_buffer state?

This would be counterintuitive (it contradicts the function name). And set_wakeup_fd() also does not return the old value of the warn_on_full_buffer parameter, so the different behavior would be inconsistent. This is certainly a problem, but there is nothing that can be done about it (sadly). In any save-restore sequence, users already have to ignore the old warn_on_full_buffer value (see aioguest, trio), and adding a way to get the old value would only complicate signal handling.

[anand-official]

Thanks for the note , understood. I’ll make sure to review and curate responses more carefully.

I agree that get_wakeup_fd() should just return the fd to keep the API consistent with set_wakeup_fd(). Exposing the warn_on_full_buffer state would be out of place.

[mvanhorn]

I've submitted an implementation in PR #145726. Adds signal.get_wakeup_fd() that reads wakeup.fd directly without modifying it, avoiding the race condition in the current set/restore workaround.