signal - 为异步事件设置处理程序¶
源代码: Lib/signal.py
此模块提供了在 Python 中使用信号处理程序的机制。
通用规则¶
signal.signal() 函数允许定义在接收到信号时要执行的自定义处理程序。安装了少量默认处理程序：SIGPIPE 被忽略（因此管道和套接字上的写入错误可以作为普通的 Python 异常报告），并且如果父进程没有更改 SIGINT，则将其转换为 KeyboardInterrupt 异常。
特定信号的处理程序一旦设置，就会一直安装，直到被显式重置（Python 模拟 BSD 风格的接口，而不管底层实现如何），但 SIGCHLD 的处理程序除外，它遵循底层实现。
在 WebAssembly 平台 wasm32-emscripten 和 wasm32-wasi 上，信号是模拟的，因此行为方式不同。在这些平台上，有几个函数和信号不可用。
Python 信号处理程序的执行¶
Python 信号处理程序不会在低级（C）信号处理程序内部执行。相反，低级信号处理程序会设置一个标志，告诉 虚拟机 在稍后的时间点（例如，在下一个 字节码 指令处）执行相应的 Python 信号处理程序。这会导致以下后果
捕获由 C 代码中的无效操作引起的同步错误（如
SIGFPE或SIGSEGV）意义不大。Python 将从信号处理程序返回到 C 代码，这可能会再次引发相同的信号，导致 Python 似乎挂起。从 Python 3.3 开始，您可以使用faulthandler模块来报告同步错误。纯粹用 C 实现的长时间运行的计算（例如，对大量文本进行正则表达式匹配）可能会不间断地运行任意长的时间，而不管接收到任何信号。Python 信号处理程序将在计算完成后被调用。
如果处理程序引发异常，则会在主线程中“凭空”引发异常。有关讨论，请参阅下面的 说明。
信号和线程¶
Python 信号处理程序总是在主解释器的 Python 主线程中执行，即使信号是在另一个线程中接收到的。这意味着信号不能用作线程间通信的方式。您可以改用 threading 模块中的同步原语。
此外，只有主解释器的主线程才允许设置新的信号处理程序。
模块内容¶
在 3.5 版更改: 信号 (SIG*)、处理程序 (SIG_DFL、SIG_IGN) 和信号掩码 (SIG_BLOCK、SIG_UNBLOCK、SIG_SETMASK) 相关的常量（如下所示）已转换为 枚举（分别为 Signals、Handlers 和 Sigmasks）。getsignal()、pthread_sigmask()、sigpending() 和 sigwait() 函数返回人类可读的 枚举 作为 Signals 对象。
signal 模块定义了三个枚举
- class signal.Signals¶
SIG* 常量和 CTRL_* 常量的
enum.IntEnum集合。3.5 版新增。
- class signal.Handlers¶
常量
SIG_DFL和SIG_IGN的enum.IntEnum集合。3.5 版新增。
- class signal.Sigmasks¶
常量
SIG_BLOCK、SIG_UNBLOCK和SIG_SETMASK的enum.IntEnum集合。可用性：Unix。
有关详细信息，请参阅手册页 sigprocmask(2) 和 pthread_sigmask(3)。
3.5 版新增。
signal 模块中定义的变量为
- signal.SIG_DFL¶
这是两种标准信号处理选项之一；它将简单地为信号执行默认函数。例如，在大多数系统上，
SIGQUIT的默认操作是转储核心并退出，而SIGCHLD的默认操作是简单地忽略它。
- signal.SIG_IGN¶
这是另一个标准信号处理程序，它将简单地忽略给定的信号。
- signal.SIGFPE¶
浮点异常。例如，除以零。
另请参阅
当除法或模运算的第二个参数为零时，将引发
ZeroDivisionError。
- signal.SIGILL¶
非法指令。
- signal.SIGINT¶
来自键盘的中断 (CTRL + C)。
默认操作是引发
KeyboardInterrupt。
- signal.SIGSEGV¶
段错误：无效的内存引用。
- signal.SIGSTKFLT¶
协处理器上的堆栈错误。Linux 内核不会引发此信号：它只能在用户空间中引发。
3.11 版新增。
- signal.SIGTERM¶
终止信号。
- SIG*
所有信号编号均以符号方式定义。例如，挂断信号定义为
signal.SIGHUP；变量名称与 C 程序中使用的名称相同，如<signal.h>中所示。Unix 手册页中的“signal()”列出了现有信号（在某些系统上是 signal(2)，在其他系统上，列表在 signal(7) 中）。请注意，并非所有系统都定义相同的信号名称集；此模块仅定义系统定义的名称。
- signal.NSIG¶
比最高信号编号大一。使用
valid_signals()获取有效的信号编号。
- signal.ITIMER_VIRTUAL¶
仅当进程正在执行时才递减间隔定时器，并在到期时发送 SIGVTALRM。
- signal.ITIMER_PROF¶
当进程执行和系统代表进程执行时，都会递减间隔定时器。与 ITIMER_VIRTUAL 相结合，此定时器通常用于分析应用程序在用户空间和内核空间中花费的时间。到期时发送 SIGPROF。
- signal.SIG_BLOCK¶
pthread_sigmask()的 how 参数的可能值，表示要阻塞信号。3.3 版新增。
- signal.SIG_UNBLOCK¶
传递给
pthread_sigmask()的 how 参数的一个可能值，表示要解除信号阻塞。3.3 版新增。
- signal.SIG_SETMASK¶
传递给
pthread_sigmask()的 how 参数的一个可能值，表示要替换信号掩码。3.3 版新增。
signal 模块定义了一个异常
- 异常 signal.ItimerError¶
当底层
setitimer()或getitimer()实现发生错误时引发。如果向setitimer()传递了无效的间隔计时器或负时间，则预期会出现此错误。此错误是OSError的子类型。
signal 模块定义了以下函数
- signal.alarm(time)¶
如果 time 不为零，则此函数请求在 time 秒后向进程发送
SIGALRM信号。任何先前安排的警报都将被取消（一次只能安排一个警报）。然后，返回值是在传递任何先前设置的警报之前的秒数。如果 time 为零，则不安排警报，并且取消任何已安排的警报。如果返回值为零，则当前未安排警报。
- signal.getsignal(signalnum)¶
返回信号 signalnum 的当前信号处理程序。返回值可以是可调用的 Python 对象，也可以是特殊值
signal.SIG_IGN、signal.SIG_DFL或None之一。这里，signal.SIG_IGN表示先前已忽略该信号，signal.SIG_DFL表示先前正在使用默认的信号处理方式，而None表示先前的信号处理程序不是从 Python 安装的。
- signal.strsignal(signalnum)¶
返回信号 signalnum 的描述，例如
SIGINT的“中断”。如果 signalnum 没有描述，则返回None。如果 signalnum 无效，则引发ValueError。3.8 版中的新内容。
- signal.valid_signals()¶
返回此平台上有效的信号编号集。如果系统保留了一些信号供内部使用，则这可能小于
range(1, NSIG)。3.8 版中的新内容。
- signal.pause()¶
使进程休眠，直到收到信号；然后将调用相应的处理程序。不返回任何内容。
- signal.raise_signal(signum)¶
向调用进程发送信号。不返回任何内容。
3.8 版中的新内容。
- signal.pidfd_send_signal(pidfd, sig, siginfo=None, flags=0)¶
向文件描述符 pidfd 引照的进程发送信号 sig。Python 当前不支持 siginfo 参数；它必须是
None。提供 flags 参数是为了将来的扩展；当前未定义任何标志值。有关更多信息，请参见 pidfd_send_signal(2) 手册页。
可用性：Linux >= 5.1
3.9 版中的新内容。
- signal.pthread_kill(thread_id, signalnum)¶
将信号 signalnum 发送到线程 thread_id，该线程与调用方位于同一进程中。目标线程可以执行任何代码（Python 或非 Python）。但是，如果目标线程正在执行 Python 解释器，则 Python 信号处理程序将由主解释器的主线程执行。因此，向特定 Python 线程发送信号的唯一意义是强制运行的系统调用失败并返回
InterruptedError。使用
threading.get_ident()或ident属性（来自threading.Thread对象）获取 thread_id 的合适值。如果 signalnum 为 0，则不发送任何信号，但仍会执行错误检查；这可用于检查目标线程是否仍在运行。
引发带有参数
thread_id、signalnum的审计事件signal.pthread_kill。可用性：Unix。
有关详细信息，请参阅手册页 pthread_kill(3)。
另请参阅
os.kill()。3.3 版新增。
- signal.pthread_sigmask(how, mask)¶
获取和/或更改调用线程的信号掩码。信号掩码是当前为调用方阻止传递的信号集。以信号集的形式返回旧的信号掩码。
调用的行为取决于 how 的值，如下所示。
SIG_BLOCK：被阻止信号的集合是当前集合和 mask 参数的并集。SIG_UNBLOCK：从当前被阻止信号集中删除 mask 中的信号。允许尝试解除未被阻止的信号的阻塞。SIG_SETMASK：被阻止信号集设置为 mask 参数。
mask 是一组信号编号（例如 {
signal.SIGINT,signal.SIGTERM}）。使用valid_signals()获取包含所有信号的完整掩码。例如，
signal.pthread_sigmask(signal.SIG_BLOCK, [])读取调用线程的信号掩码。SIGKILL和SIGSTOP不能被阻止。可用性：Unix。
有关详细信息，请参阅手册页 sigprocmask(2) 和 pthread_sigmask(3)。
另请参阅
pause()、sigpending()和sigwait()。3.3 版新增。
- signal.setitimer(which, seconds, interval=0.0)¶
设置由 which 指定的给定间隔计时器（
signal.ITIMER_REAL、signal.ITIMER_VIRTUAL或signal.ITIMER_PROF之一），使其在 seconds 秒后触发（接受浮点数，与alarm()不同），之后每隔 interval 秒触发一次（如果 interval 不为零）。可以通过将 seconds 设置为零来清除由 which 指定的间隔计时器。当间隔计时器触发时，会向进程发送一个信号。发送的信号取决于正在使用的计时器；
signal.ITIMER_REAL将传递SIGALRM，signal.ITIMER_VIRTUAL发送SIGVTALRM，而signal.ITIMER_PROF将传递SIGPROF。旧值作为元组返回：(delay, interval)。
尝试传递无效的间隔计时器将导致
ItimerError。可用性：Unix。
- signal.set_wakeup_fd(fd, *, warn_on_full_buffer=True)¶
将唤醒文件描述符设置为 fd。当收到信号时，信号编号将作为单个字节写入 fd。库可以使用它来唤醒 poll 或 select 调用，从而允许完全处理信号。
返回旧的唤醒 fd（如果未启用文件描述符唤醒，则返回 -1）。如果 fd 为 -1，则禁用文件描述符唤醒。如果不是 -1，则 fd 必须是非阻塞的。在再次调用 poll 或 select 之前，库最多可以从 fd 中删除任何字节。
启用线程后，只能从主解释器的主线程调用此函数；尝试从其他线程调用它将导致引发
ValueError异常。有两种常用方法可以使用此函数。在这两种方法中，您都使用 fd 在信号到达时唤醒，但它们在如何确定已到达的信号方面有所不同。
在第一种方法中，我们从 fd 的缓冲区中读取数据，字节值为您提供信号编号。这很简单，但在极少数情况下可能会遇到问题：通常 fd 的缓冲区空间有限，如果太多信号到达太快，则缓冲区可能会变满，并且一些信号可能会丢失。如果您使用这种方法，那么您应该设置
warn_on_full_buffer=True，这至少会在信号丢失时导致向 stderr 打印警告。在第二种方法中，我们仅将唤醒 fd 用于唤醒，而忽略实际的字节值。在这种情况下，我们只关心 fd 的缓冲区是空的还是非空的；满缓冲区根本不表示有问题。如果您使用这种方法，那么您应该设置
warn_on_full_buffer=False，这样您的用户就不会被虚假的警告消息所迷惑。在 3.5 版更改: 在 Windows 上，该函数现在也支持套接字句柄。
在 3.7 版更改: 添加了
warn_on_full_buffer参数。
- signal.siginterrupt(signalnum, flag)¶
更改系统调用重启行为：如果 flag 为
False，则系统调用在被信号 signalnum 中断时将重新启动，否则系统调用将被中断。不返回任何值。可用性：Unix。
有关详细信息，请参阅手册页 siginterrupt(3)。
请注意，使用
signal()安装信号处理程序会将重启行为重置为可中断，方法是针对给定信号隐式调用带有 true flag 值的siginterrupt()。
- signal.signal(signalnum, handler)¶
将信号 signalnum 的处理程序设置为函数 handler。 handler 可以是一个接受两个参数的可调用 Python 对象（见下文），也可以是特殊值
signal.SIG_IGN或signal.SIG_DFL之一。将返回之前的信号处理程序（请参阅上面getsignal()的描述）。（有关详细信息，请参阅 Unix 手册页 signal(2)。）启用线程后，只能从主解释器的主线程调用此函数；尝试从其他线程调用它将导致引发
ValueError异常。使用两个参数调用 handler：信号编号和当前堆栈帧（
None或帧对象；有关帧对象的描述，请参阅 类型层次结构中的描述 或inspect模块中的属性描述）。在 Windows 上，
signal()只能使用SIGABRT、SIGFPE、SIGILL、SIGINT、SIGSEGV、SIGTERM或SIGBREAK调用。在任何其他情况下，都会引发ValueError。请注意，并非所有系统都定义相同的信号名称集；如果未将信号名称定义为SIG*模块级常量，则会引发AttributeError。
- signal.sigpending()¶
检查等待传递给调用线程的信号集（即，在阻塞时引发的信号）。返回挂起的信号集。
可用性：Unix。
有关详细信息，请参阅手册页 sigpending(2)。
另请参阅
pause()、pthread_sigmask()和sigwait()。3.3 版新增。
- signal.sigwait(sigset)¶
暂停调用线程的执行，直到传递信号集 sigset 中指定的信号之一。该函数接受信号（将其从挂起的信号列表中删除），并返回信号编号。
可用性：Unix。
有关详细信息，请参阅手册页 sigwait(3)。
另请参阅
pause()、pthread_sigmask()、sigpending()、sigwaitinfo()和sigtimedwait()。3.3 版新增。
- signal.sigwaitinfo(sigset)¶
暂停调用线程的执行，直到传递信号集 sigset 中指定的信号之一。该函数接受信号并将其从挂起的信号列表中删除。如果 sigset 中的某个信号已在调用线程中挂起，则该函数将立即返回有关该信号的信息。不会为传递的信号调用信号处理程序。如果函数被 sigset 中没有的信号中断，则会引发
InterruptedError。返回值是一个对象，表示
siginfo_t结构中包含的数据，即：si_signo、si_code、si_errno、si_pid、si_uid、si_status、si_band。可用性：Unix。
有关详细信息，请参阅手册页 sigwaitinfo(2)。
另请参阅
pause()、sigwait()和sigtimedwait()。3.3 版新增。
在 3.5 版更改: 如果函数被 sigset 中没有的信号中断并且信号处理程序没有引发异常，则现在会重试该函数（有关基本原理，请参阅 PEP 475）。
- signal.sigtimedwait(sigset, timeout)¶
与
sigwaitinfo()类似，但需要一个额外的 timeout 参数来指定超时时间。如果 timeout 指定为0，则执行轮询。如果发生超时，则返回None。可用性：Unix。
有关详细信息，请参阅手册页 sigtimedwait(2)。
另请参阅
pause()、sigwait()和sigwaitinfo()。3.3 版新增。
版本 3.5 中的变化： 如果函数被 sigset 中没有的信号中断，并且信号处理程序没有引发异常，则现在使用重新计算的 timeout 重试该函数（有关基本原理，请参阅 PEP 475）。
示例¶
这是一个最小的示例程序。它使用 alarm() 函数来限制打开文件所花费的时间；如果文件用于可能未打开的串行设备，这将非常有用，因为这通常会导致 os.open() 无限期挂起。解决方案是在打开文件之前设置一个 5 秒的警报；如果操作花费的时间太长，则会发送警报信号，并且处理程序会引发异常。
import signal, os
def handler(signum, frame):
signame = signal.Signals(signum).name
print(f'Signal handler called with signal {signame} ({signum})')
raise OSError("Couldn't open device!")
# Set the signal handler and a 5-second alarm
signal.signal(signal.SIGALRM, handler)
signal.alarm(5)
# This open() may hang indefinitely
fd = os.open('/dev/ttyS0', os.O_RDWR)
signal.alarm(0) # Disable the alarm
关于 SIGPIPE 的说明¶
将程序的输出通过管道传输到 head(1) 等工具会导致在标准输出的接收器提前关闭时向进程发送 SIGPIPE 信号。这会导致出现类似 BrokenPipeError: [Errno 32] Broken pipe 的异常。要处理这种情况，请包装您的入口点以捕获此异常，如下所示
import os
import sys
def main():
try:
# simulate large output (your code replaces this loop)
for x in range(10000):
print("y")
# flush output here to force SIGPIPE to be triggered
# while inside this try block.
sys.stdout.flush()
except BrokenPipeError:
# Python flushes standard streams on exit; redirect remaining output
# to devnull to avoid another BrokenPipeError at shutdown
devnull = os.open(os.devnull, os.O_WRONLY)
os.dup2(devnull, sys.stdout.fileno())
sys.exit(1) # Python exits with error code 1 on EPIPE
if __name__ == '__main__':
main()
不要将 SIGPIPE 的处置设置为 SIG_DFL，以避免 BrokenPipeError。这样做会导致您的程序在程序仍在写入任何套接字连接时，只要该连接中断，程序就会意外退出。
关于信号处理程序和异常的说明¶
如果信号处理程序引发异常，则该异常将传播到主线程，并且可能会在任何 字节码 指令之后引发。最值得注意的是，KeyboardInterrupt 可能会在执行过程中的任何时候出现。大多数 Python 代码（包括标准库）都无法对此进行稳健处理，因此 KeyboardInterrupt（或由信号处理程序导致的任何其他异常）在极少数情况下可能会使程序处于意外状态。
为了说明这个问题，请考虑以下代码
class SpamContext:
def __init__(self):
self.lock = threading.Lock()
def __enter__(self):
# If KeyboardInterrupt occurs here, everything is fine
self.lock.acquire()
# If KeyboardInterrupt occurs here, __exit__ will not be called
...
# KeyboardInterrupt could occur just before the function returns
def __exit__(self, exc_type, exc_val, exc_tb):
...
self.lock.release()
对于许多程序，尤其是那些只想在 KeyboardInterrupt 上退出的程序来说，这不是问题，但是复杂或需要高可靠性的应用程序应避免从信号处理程序中引发异常。它们还应避免捕获 KeyboardInterrupt 作为正常关闭的一种手段。相反，它们应该安装自己的 SIGINT 处理程序。下面是一个避免 KeyboardInterrupt 的 HTTP 服务器示例
import signal
import socket
from selectors import DefaultSelector, EVENT_READ
from http.server import HTTPServer, SimpleHTTPRequestHandler
interrupt_read, interrupt_write = socket.socketpair()
def handler(signum, frame):
print('Signal handler called with signal', signum)
interrupt_write.send(b'\0')
signal.signal(signal.SIGINT, handler)
def serve_forever(httpd):
sel = DefaultSelector()
sel.register(interrupt_read, EVENT_READ)
sel.register(httpd, EVENT_READ)
while True:
for key, _ in sel.select():
if key.fileobj == interrupt_read:
interrupt_read.recv(1)
return
if key.fileobj == httpd:
httpd.handle_request()
print("Serving on port 8000")
httpd = HTTPServer(('', 8000), SimpleHTTPRequestHandler)
serve_forever(httpd)
print("Shutdown...")