Doc: signal.sig(timed)wait do not work outside the main thread

[petr-motejlek]

BPO	29374
Nosy	@vadmium, @petr-motejlek

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2017-01-25.17:25:31.331>
labels = ['3.11', 'type-feature', 'docs']
title = 'Doc: signal.sig(timed)wait do not work outside the main thread'
updated_at = <Date 2021-10-22.10:01:01.554>
user = 'https://github.com/petr-motejlek'

bugs.python.org fields:

activity = <Date 2021-10-22.10:01:01.554>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2017-01-25.17:25:31.331>
creator = 'petr@motejlek.net'
dependencies = []
files = []
hgrepos = []
issue_num = 29374
keywords = []
message_count = 2.0
messages = ['286269', '286284']
nosy_count = 3.0
nosy_names = ['docs@python', 'martin.panter', 'petr@motejlek.net']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue29374'
versions = ['Python 3.11']

[petr-motejlek]

Hi,

The documentation for signal.signal() clearly states that it is only supposed to be called on MainThread

However, it does not say so for the signal.sigwait() and neither signal.sigtimedwait()

I think this is an error on the documentation side of things (unless I misread it). When either signal.sigwait or signal.sigtimedwait are called outside MainThread, they simply never catch any signals (signal.sigwait blocks indefinitely)

I did not test this on Windows, but on both Linux and OS X the behavior is the same

Consider the below simple code

  import signal
  import os
  def sigwait():
    print("Send me a signal, my PID is {p}".format(p=os.getpid()))  
    print("Got the signal: {i}".format(i=signal.sigwait((signal.SIGUSR1,))))

If sigwait() is called on MainThread and the process receives SIGUSR1, "Got the signal: ..." gets printed. However, calling sigwait in a different thread blocks the thread indefinitely. The behavior is the same with signal.sigtimedwait() as well

[vadmium]

This works for me on Linux:

>>> signal.pthread_sigmask(signal.SIG_BLOCK, {signal.SIGUSR1})
set()
>>> import threading
>>> t = threading.Thread(target=sigwait)
>>> t.start()
Send me a signal, my PID is 24197
>>> os.kill(os.getpid(), signal.SIGUSR1)
Got the signal: 10
>>> t.join()

Posix <http://pubs.opengroup.org/onlinepubs/9699919799/functions/sigwait.html\> only defines sigwait() if the signals are already blocked. Two reasons behind this come to mind:

1. There would be a race where the signal handler may be called first (or the signal may be ignored) at the OS level, and the sigwait() function will miss the signal and block.

2. If the signal is handled in the context of another thread that isn’t using sigwait(), it may be consumed (handled or ignored) in the context of the other thread, with no effect on your sigwait() call.

This detail of blocking the signal seems to be a common error, so maybe the Python documentation could help point it out. (bpo-25868 comes to mind; there is a test case that IMO should block a signal before waiting for it.)