From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Mon, 14 Apr 2025 16:52:36 +0000 (+0200)
Subject: [3.13] gh-131803: Clarify that you must register signal handlers for set_wakeup_fd... 
X-Git-Tag: v3.13.4~273
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=bdff88b9aad5d799e0e70755f42811e2fdf16994;p=thirdparty%2FPython%2Fcpython.git

[3.13] gh-131803: Clarify that you must register signal handlers for set_wakeup_fd (GH-131859) (#132522)

gh-131803: Clarify that you must register signal handlers for set_wakeup_fd (GH-131859)
(cherry picked from commit 939476bbbb57ec3348c60df7c8f67c92038c8c89)

Co-authored-by: Jeremy Fleischman <jeremyfleischman@gmail.com>
---

diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index 17fcb2b37079..c28841dbb8cf 100644
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -510,10 +510,12 @@ The :mod:`signal` module defines the following functions:
 
 .. function:: set_wakeup_fd(fd, *, warn_on_full_buffer=True)
 
-   Set the wakeup file descriptor to *fd*.  When a signal is received, the
-   signal number is written as a single byte into the fd.  This can be used by
-   a library to wakeup a poll or select call, allowing the signal to be fully
-   processed.
+   Set the wakeup file descriptor to *fd*.  When a signal your program has
+   registered a signal handler for is received, the signal number is written as
+   a single byte into the fd.  If you haven't registered a signal handler for
+   the signals you care about, then nothing will be written to the wakeup fd.
+   This can be used by a library to wakeup a poll or select call, allowing the
+   signal to be fully processed.
 
    The old wakeup fd is returned (or -1 if file descriptor wakeup was not
    enabled).  If *fd* is -1, file descriptor wakeup is disabled.