Alarms and Interval Timers

Plenty of calls in a Unix Python process have no timeout of their own: a compiled library entry point, a device read, a legacy client that exposes no deadline argument. The oldest and still the most common answer is to make the kernel interrupt you on a clock, and to turn that interruption into an ordinary Python exception. ### The three moving parts **1. A disposition that is not the default.** `SIGALRM` is signal number 14 and its default disposition is *terminate the process*. If you arm an alarm and never register a handler, the process dies when it fires — no traceback, no `finally` blocks, no `atexit` callbacks, and a shell exit status of 142 (128 + 14). So the first line of the pattern is always `signal.signal(signal.SIGALRM, on_alarm)`. **2. A handler that raises.** The handler receives `(signum, frame)` and does one useful thing: `raise TimeoutError(...)`. It is the *raise* that produces the timeout — `signal.alarm` itself never raises anything. Because CPython only runs Python-level signal handlers between bytecode instructions in the main thread, the exception surfaces at whatever bytecode boundary the main thread reaches next. For a blocking syscall that boundary comes almost immediately: the signal interrupts the syscall, the interpreter notices the pending handler, runs it, and the exception propagates out of the call site as if the call had raised. **3. Arming and disarming.** `signal.alarm(n)` schedules the signal for approximately `n` seconds from now; `signal.alarm(0)` cancels a pending one. The argument is an integer — `signal.alarm(0.5)` raises `TypeError`, because whole seconds are all the underlying call accepts. The return value is the number of seconds remaining on the previously scheduled alarm, or `0` if none was armed, which is the only bookkeeping the API gives you. ### Why the finally block is not optional There is exactly **one** of these timers per process. Arming a five-second deadline around a call that finishes in forty milliseconds leaves 4.96 seconds on the clock. Nobody cancelled it, so it fires later — inside a different function, inside cleanup code, inside a long test run — and raises `TimeoutError` from a stack frame that never asked for a deadline. That is one of the classic ways this pattern turns into a mystery bug, and the cure is mechanical: arm in `try`, disarm in `finally`. The same one-timer-per-process fact explains why nesting does not work naively. An inner deadline overwrites the outer one; when the inner region exits and calls `signal.alarm(0)`, it has also cancelled the outer deadline. A serious helper saves the returned remaining time and restores it, or refuses to nest. ### What it can and cannot interrupt The mechanism is only as good as the interpreter's chance to run the handler. A blocking *syscall* is interrupted by the signal, so the eval loop gets control back quickly and the exception lands where you want it. A long **compiled** computation that neither returns to the interpreter nor checks for pending signals is a different story: the handler cannot run until that call finally returns, so the deadline is simply late — sometimes uselessly so. The C-level handler CPython installs does almost nothing but set a flag; all the real work waits for the eval loop. ### The shape to write ```python import signal def on_alarm(signum, frame): raise TimeoutError("sensor read exceeded its budget") previous = signal.signal(signal.SIGALRM, on_alarm) signal.alarm(3) try: result = read_from_device() # no timeout argument of its own finally: signal.alarm(0) signal.signal(signal.SIGALRM, previous) ``` Capturing and restoring the previous handler matters once more than one piece of code in the process cares about `SIGALRM`; `signal.signal` returns the old handler for exactly that reason, and it may be `signal.SIG_DFL`. ### Limits worth saying out loud This is a Unix-only mechanism — there is no `SIGALRM` on Windows. It is whole-seconds only; `signal.setitimer(signal.ITIMER_REAL, 0.25)` is the fractional-resolution sibling and shares the same underlying timer. And it only works from the process's main thread, because that is where handler registration is allowed and where the handler runs. If the call you want to bound already accepts a deadline of its own, use that instead: a real timeout argument beats an out-of-band signal every time. `signal.alarm` is the tool for the calls that offer you nothing.