raise_signal docs imply process receives signal not thread

Documentation

The documentation of signal.raise_signal(signum) is:

Sends a signal to the calling process

Which somewhat implies the signal is sent to the main thread of the process, ie. equivalent to os.kill(os.getpid(), signum). In actuality the signal is sent to the calling thread, which with the nuance of how Python executes signal handlers can lead to subtly different behaviour with regard to interrupting blocking functions.

The attached example shows how this interpretation can lead to bugs.

$ python example.py kill
Waiting for signal...
Handling signal 15
Wait interrupted by signal

$ python example.py raise_signal
Waiting for signal...

example.py

import os
import signal
import sys
import threading
import time

# Register a handler to flag an event when a signal is received
signalled_flag = threading.Event()


def signal_handler(signum, _frame):
    print(f"Handling signal {signum}")
    signalled_flag.set()


signal.signal(signal.SIGTERM, signal_handler)


# Raise the signal in a separate thread once the main thread is waiting on said event
def do_raise_signal():
    time.sleep(0.01)
    signal.raise_signal(signal.SIGTERM)


def do_kill_process():
    time.sleep(0.01)
    os.kill(os.getpid(), signal.SIGTERM)


match sys.argv:
    case [_, "raise_signal"]:
        thread = threading.Thread(target=do_raise_signal)
    case [_, "kill"]:
        thread = threading.Thread(target=do_kill_process)
    case _:
        print(f"Usage: {sys.argv[0]} [raise_signal|kill]")
        sys.exit(1)


thread.start()

# Wait for the signal to be received
print("Waiting for signal...")
signalled_flag.wait()
print("Wait interrupted by signal")

Linked PRs

• gh-129167

Bắt đầu với mục tài liệu về signal.raise_signal(signum) và đọc hướng dẫn được liên kết về tín hiệu và luồng. Làm rõ rằng tín hiệu được gửi đến luồng đang gọi, thay vì ngụ ý rằng tín hiệu được gửi đến tiến trình hoặc luồng chính, sau đó kiểm tra để bảo đảm cách diễn đạt và các ví dụ trong tài liệu vẫn nhất quán.