6.5. Сигналы и PID 1 в Python

   ядро доставляет сигнал
          │
          ▼
   C-обработчик Python устанавливает флаг
   и записывает байт в wakeup-fd
          │
          ▼
   интерпретатор продолжает выполнение
          │
          ▼
   между инструкциями байт-кода проверяет флаги
          │
          ▼
   вызывает Python-обработчик в ГЛАВНОМ потоке

import signal

_shutdown = False


def handle_shutdown(signum, frame):
    """Только выставляет флаг — вся работа в основном цикле."""
    global _shutdown
    _shutdown = True


signal.signal(signal.SIGTERM, handle_shutdown)

while not _shutdown:
    do_work()

cleanup()

import asyncio
import signal


async def main():
    loop = asyncio.get_running_loop()
    stop = asyncio.Event()

    for sig in (signal.SIGTERM, signal.SIGINT):
        loop.add_signal_handler(sig, stop.set)

    await stop.wait()
    await cleanup()

from contextlib import asynccontextmanager

from fastapi import FastAPI


@asynccontextmanager
async def lifespan(app: FastAPI):
    # startup
    pool = await create_pool()
    app.state.pool = pool
    yield
    # shutdown: вызывается при SIGTERM
    await pool.close()


app = FastAPI(lifespan=lifespan)

def handle_shutdown(signum, frame):
    global _shutdown
    _shutdown = True
    for proc in children:
        proc.terminate()      # посылает SIGTERM

for proc in children:
    try:
        proc.wait(timeout=5)
    except subprocess.TimeoutExpired:
        proc.kill()

ValueError: signal only works in main thread of the main interpreter

# плохо: реакция на сигнал через час
time.sleep(3600)

# хорошо: реакция в пределах 0.5 секунды
for _ in range(7200):
    if _shutdown:
        break
    time.sleep(0.5)

mkdir -p /tmp/pysig && cd /tmp/pysig

cat > sync_worker.py <<'PY'
"""Синхронный worker с корректным завершением."""
import os
import signal
import sys
import time

_shutdown = False


def handle_shutdown(signum, _frame):
    """Только выставляет флаг: вся работа — в основном цикле."""
    global _shutdown
    print(f"[сигнал] получен {signal.Signals(signum).name}", flush=True)
    _shutdown = True


signal.signal(signal.SIGTERM, handle_shutdown)
signal.signal(signal.SIGINT, handle_shutdown)

print(f"[старт] PID={os.getpid()}", flush=True)

n = 0
while not _shutdown:
    n += 1
    print(f"[работа] итерация {n}", flush=True)
    # короткий sleep в цикле: реакция на сигнал в пределах 0.5 c
    for _ in range(2):
        if _shutdown:
            break
        time.sleep(0.5)

print("[завершение] закрываю ресурсы...", flush=True)
time.sleep(0.3)
print(f"[завершение] выполнено итераций: {n}", flush=True)
sys.exit(0)
PY

cat > Dockerfile.sync <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
COPY sync_worker.py /app.py
CMD ["python", "/app.py"]
EOF

docker build -q -f Dockerfile.sync -t sig:sync . > /dev/null
docker run -d --name sync-t sig:sync > /dev/null
sleep 3

s="$(date +%s.%N)"; docker stop sync-t > /dev/null; e="$(date +%s.%N)"
printf 'время stop: %.2f c, код: %s\n' \
    "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')" \
    "$(docker inspect sync-t --format '{{.State.ExitCode}}')"
docker logs sync-t 2>&1 | tail -4
docker rm sync-t > /dev/null

время stop: 0.84 c, код: 0
[работа] итерация 3
[сигнал] получен SIGTERM
[завершение] закрываю ресурсы...
[завершение] выполнено итераций: 3

cat > long_sleep.py <<'PY'
"""Один длинный sleep вместо цикла коротких."""
import signal
import sys
import time

_shutdown = False


def handle(signum, _frame):
    global _shutdown
    print(f"[сигнал] получен {signal.Signals(signum).name}", flush=True)
    _shutdown = True


signal.signal(signal.SIGTERM, handle)
print("[старт] засыпаю на 60 секунд одним вызовом", flush=True)

while not _shutdown:
    time.sleep(60)      # реакция только после возврата

print("[завершение] штатно", flush=True)
sys.exit(0)
PY

cat > Dockerfile.longsleep <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
COPY long_sleep.py /app.py
CMD ["python", "/app.py"]
EOF

docker build -q -f Dockerfile.longsleep -t sig:longsleep . > /dev/null
docker run -d --name long-t sig:longsleep > /dev/null
sleep 2

s="$(date +%s.%N)"; docker stop long-t > /dev/null; e="$(date +%s.%N)"
printf 'время stop: %.2f c, код: %s\n' \
    "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')" \
    "$(docker inspect long-t --format '{{.State.ExitCode}}')"
docker logs long-t 2>&1 | tail -3
docker rm long-t > /dev/null

время stop: 0.31 c, код: 0
[старт] засыпаю на 60 секунд одним вызовом
[сигнал] получен SIGTERM
[завершение] штатно

cat > blocking_io.py <<'PY'
"""Блокирующий вызов без таймаута задерживает реакцию на сигнал."""
import signal
import socket
import sys

_shutdown = False


def handle(signum, _frame):
    global _shutdown
    print(f"[сигнал] получен {signal.Signals(signum).name}", flush=True)
    _shutdown = True


signal.signal(signal.SIGTERM, handle)

srv = socket.socket()
srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
srv.bind(("0.0.0.0", 9000))
srv.listen(1)
print("[старт] жду соединения БЕЗ таймаута", flush=True)

while not _shutdown:
    try:
        conn, _ = srv.accept()   # блокируется бесконечно
        conn.close()
    except OSError:
        break

print("[завершение] штатно", flush=True)
sys.exit(0)
PY

cat > Dockerfile.blocking <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
COPY blocking_io.py /app.py
CMD ["python", "/app.py"]
EOF

docker build -q -f Dockerfile.blocking -t sig:blocking . > /dev/null
docker run -d --name block-t sig:blocking > /dev/null
sleep 2

s="$(date +%s.%N)"; docker stop block-t > /dev/null; e="$(date +%s.%N)"
printf 'время stop: %.2f c, код: %s\n' \
    "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')" \
    "$(docker inspect block-t --format '{{.State.ExitCode}}')"
docker logs block-t 2>&1 | tail -2
docker rm block-t > /dev/null

время stop: 10.29 c, код: 137
[старт] жду соединения БЕЗ таймаута
[сигнал] получен SIGTERM

sed 's/srv.listen(1)/srv.listen(1)\nsrv.settimeout(0.5)/; s/жду соединения БЕЗ таймаута/жду соединения с таймаутом 0.5 c/' \
    blocking_io.py > blocking_fixed.py
sed -i 's/except OSError:/except socket.timeout:\n        continue\n    except OSError:/' blocking_fixed.py

cat > Dockerfile.blockfix <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
COPY blocking_fixed.py /app.py
CMD ["python", "/app.py"]
EOF

docker build -q -f Dockerfile.blockfix -t sig:blockfix . > /dev/null
docker run -d --name blockfix-t sig:blockfix > /dev/null
sleep 2
s="$(date +%s.%N)"; docker stop blockfix-t > /dev/null; e="$(date +%s.%N)"
printf 'с таймаутом: %.2f c, код: %s\n' \
    "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')" \
    "$(docker inspect blockfix-t --format '{{.State.ExitCode}}')"
docker rm blockfix-t > /dev/null

с таймаутом: 0.73 c, код: 0

cat > thread_handler.py <<'PY'
"""Попытка установить обработчик из дочернего потока."""
import signal
import threading


def worker():
    try:
        signal.signal(signal.SIGTERM, lambda s, f: None)
        print("обработчик установлен из потока — неожиданно", flush=True)
    except ValueError as exc:
        print(f"ОШИБКА: {exc}", flush=True)


t = threading.Thread(target=worker)
t.start()
t.join()
PY

docker run --rm -v "$PWD/thread_handler.py:/app.py:ro" \
    -e PYTHONUNBUFFERED=1 python:3.13-slim python /app.py

ОШИБКА: signal only works in main thread of the main interpreter

cat > threaded_app.py <<'PY'
"""Многопоточное приложение: обработчик в главном потоке, потоки читают флаг."""
import os
import signal
import sys
import threading
import time

_shutdown = threading.Event()


def handle_shutdown(signum, _frame):
    print(f"[сигнал] {signal.Signals(signum).name}", flush=True)
    _shutdown.set()


# Обработчик устанавливается в ГЛАВНОМ потоке, до запуска рабочих
signal.signal(signal.SIGTERM, handle_shutdown)
signal.signal(signal.SIGINT, handle_shutdown)


def worker(worker_id: int) -> None:
    n = 0
    # Event.wait с таймаутом: и пауза, и проверка флага одновременно
    while not _shutdown.wait(timeout=1.0):
        n += 1
        print(f"[поток {worker_id}] итерация {n}", flush=True)
    print(f"[поток {worker_id}] завершён, итераций: {n}", flush=True)


print(f"[старт] PID={os.getpid()}", flush=True)

threads = [threading.Thread(target=worker, args=(i,)) for i in range(1, 4)]
for t in threads:
    t.start()

_shutdown.wait()
print("[главный] жду завершения потоков", flush=True)
for t in threads:
    t.join(timeout=5)

print("[главный] все потоки остановлены", flush=True)
sys.exit(0)
PY

cat > Dockerfile.threaded <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
COPY threaded_app.py /app.py
CMD ["python", "/app.py"]
EOF

docker build -q -f Dockerfile.threaded -t sig:threaded . > /dev/null
docker run -d --name thr-t sig:threaded > /dev/null
sleep 3
s="$(date +%s.%N)"; docker stop thr-t > /dev/null; e="$(date +%s.%N)"
printf 'время stop: %.2f c, код: %s\n' \
    "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')" \
    "$(docker inspect thr-t --format '{{.State.ExitCode}}')"
docker logs thr-t 2>&1 | tail -6
docker rm thr-t > /dev/null

время stop: 1.05 c, код: 0
[сигнал] SIGTERM
[поток 1] завершён, итераций: 3
[поток 2] завершён, итераций: 3
[поток 3] завершён, итераций: 3
[главный] жду завершения потоков
[главный] все потоки остановлены

cat > async_app.py <<'PY'
"""Асинхронное приложение с корректным завершением."""
import asyncio
import os
import signal


async def background_task(task_id: int, stop: asyncio.Event) -> int:
    n = 0
    while not stop.is_set():
        n += 1
        print(f"[задача {task_id}] итерация {n}", flush=True)
        try:
            await asyncio.wait_for(stop.wait(), timeout=1.0)
        except asyncio.TimeoutError:
            pass
    print(f"[задача {task_id}] остановлена, итераций: {n}", flush=True)
    return n


async def main() -> int:
    loop = asyncio.get_running_loop()
    stop = asyncio.Event()

    # add_signal_handler работает через цикл событий, а не прерывает выполнение
    for sig in (signal.SIGTERM, signal.SIGINT):
        loop.add_signal_handler(sig, stop.set)

    print(f"[старт] PID={os.getpid()}", flush=True)

    tasks = [asyncio.create_task(background_task(i, stop)) for i in range(1, 4)]

    await stop.wait()
    print("[завершение] сигнал получен, дожидаюсь задач", flush=True)

    results = await asyncio.gather(*tasks)
    print(f"[завершение] всего итераций: {sum(results)}", flush=True)

    # имитация закрытия ресурсов
    await asyncio.sleep(0.2)
    print("[завершение] ресурсы закрыты", flush=True)
    return 0


if __name__ == "__main__":
    raise SystemExit(asyncio.run(main()))
PY

cat > Dockerfile.async <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
COPY async_app.py /app.py
CMD ["python", "/app.py"]
EOF

docker build -q -f Dockerfile.async -t sig:async . > /dev/null
docker run -d --name async-t sig:async > /dev/null
sleep 3
s="$(date +%s.%N)"; docker stop async-t > /dev/null; e="$(date +%s.%N)"
printf 'время stop: %.2f c, код: %s\n' \
    "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')" \
    "$(docker inspect async-t --format '{{.State.ExitCode}}')"
docker logs async-t 2>&1 | tail -5
docker rm async-t > /dev/null

время stop: 0.51 c, код: 0
[завершение] сигнал получен, дожидаюсь задач
[задача 1] остановлена, итераций: 3
[задача 2] остановлена, итераций: 3
[задача 3] остановлена, итераций: 3
[завершение] всего итераций: 9
[завершение] ресурсы закрыты

cat > with_children.py <<'PY'
"""Уведомление дочерних процессов при завершении."""
import os
import signal
import subprocess
import sys
import time

_shutdown = False
children: list[subprocess.Popen] = []


def handle_shutdown(signum, _frame):
    global _shutdown
    print(f"[родитель] сигнал {signal.Signals(signum).name}", flush=True)
    _shutdown = True
    # уведомляем потомков: сигнал получил только PID 1
    for proc in children:
        if proc.poll() is None:
            print(f"[родитель] шлю SIGTERM потомку {proc.pid}", flush=True)
            proc.terminate()


signal.signal(signal.SIGTERM, handle_shutdown)

CHILD_CODE = """
import signal, sys, time
running = True
def h(s, f):
    global running
    print(f'[потомок {__import__("os").getpid()}] завершаюсь корректно', flush=True)
    running = False
signal.signal(signal.SIGTERM, h)
print(f'[потомок {__import__("os").getpid()}] запущен', flush=True)
while running:
    time.sleep(0.3)
print(f'[потомок {__import__("os").getpid()}] ресурсы освобождены', flush=True)
sys.exit(0)
"""

print(f"[родитель] PID={os.getpid()}", flush=True)
for _ in range(2):
    children.append(subprocess.Popen([sys.executable, "-u", "-c", CHILD_CODE]))

while not _shutdown:
    time.sleep(0.3)

print("[родитель] жду завершения потомков", flush=True)
for proc in children:
    try:
        proc.wait(timeout=5)
        print(f"[родитель] потомок {proc.pid} завершён, код {proc.returncode}", flush=True)
    except subprocess.TimeoutExpired:
        print(f"[родитель] потомок {proc.pid} не ответил — убиваю", flush=True)
        proc.kill()

print("[родитель] завершено штатно", flush=True)
sys.exit(0)
PY

cat > Dockerfile.children <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
COPY with_children.py /app.py
CMD ["python", "/app.py"]
EOF

docker build -q -f Dockerfile.children -t sig:children . > /dev/null
docker run -d --name child-t sig:children > /dev/null
sleep 2
echo "процессы в container:"
docker exec child-t ps -o pid,args | sed 's/^/  /'

s="$(date +%s.%N)"; docker stop child-t > /dev/null; e="$(date +%s.%N)"
printf 'время stop: %.2f c, код: %s\n' \
    "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')" \
    "$(docker inspect child-t --format '{{.State.ExitCode}}')"
docker logs child-t 2>&1 | tail -7
docker rm child-t > /dev/null

процессы в container:
  PID   COMMAND
      1 python /app.py
      7 /usr/local/bin/python -u -c ...
      8 /usr/local/bin/python -u -c ...
     14 ps -o pid,args
время stop: 0.68 c, код: 0
[родитель] шлю SIGTERM потомку 7
[родитель] шлю SIGTERM потомку 8
[потомок 7] завершаюсь корректно
[потомок 8] завершаюсь корректно
[потомок 7] ресурсы освобождены
[потомок 8] ресурсы освобождены
[родитель] завершено штатно

cat > asgi_app.py <<'PY'
"""ASGI-приложение: завершением управляет сервер через lifespan."""
import asyncio
import os
from contextlib import asynccontextmanager

from fastapi import FastAPI


@asynccontextmanager
async def lifespan(_app: FastAPI):
    print(f"[lifespan] startup, PID={os.getpid()}", flush=True)
    # здесь: пул соединений, прогрев кэша
    yield
    # вызывается при SIGTERM — сервер сам его обработал
    print("[lifespan] shutdown: закрываю ресурсы", flush=True)
    await asyncio.sleep(0.3)
    print("[lifespan] ресурсы закрыты", flush=True)


app = FastAPI(lifespan=lifespan)


@app.get("/")
async def root():
    return {"pid": os.getpid()}


@app.get("/slow")
async def slow():
    await asyncio.sleep(5)
    return {"done": True}
PY

cat > Dockerfile.asgi <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
RUN pip install --no-cache-dir "fastapi[standard]==0.141.1"
COPY asgi_app.py /app/asgi_app.py
WORKDIR /app
CMD ["fastapi", "run", "asgi_app.py", "--port", "8000"]
EOF

docker build -q -f Dockerfile.asgi -t sig:asgi . > /dev/null
docker run -d --name asgi-t -p 8100:8000 sig:asgi > /dev/null
sleep 6
curl -s localhost:8100/ | head -c 60; echo

s="$(date +%s.%N)"; docker stop asgi-t > /dev/null; e="$(date +%s.%N)"
printf 'время stop: %.2f c, код: %s\n' \
    "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')" \
    "$(docker inspect asgi-t --format '{{.State.ExitCode}}')"
docker logs asgi-t 2>&1 | grep lifespan
docker rm asgi-t > /dev/null

{"pid":1}
время stop: 0.62 c, код: 0
[lifespan] startup, PID=1
[lifespan] shutdown: закрываю ресурсы
[lifespan] ресурсы закрыты

docker run -d --name asgi-drain -p 8101:8000 sig:asgi > /dev/null
sleep 6
curl -s localhost:8101/slow > /tmp/slow-result.txt &
CURL_PID=$!
sleep 1
s="$(date +%s.%N)"; docker stop --timeout 20 asgi-drain > /dev/null; e="$(date +%s.%N)"
wait $CURL_PID 2>/dev/null
printf 'время stop: %.1f c (ждал завершения запроса)\n' \
    "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')"
echo -n "ответ на медленный запрос: "; cat /tmp/slow-result.txt; echo
docker rm asgi-drain > /dev/null; rm -f /tmp/slow-result.txt

время stop: 4.2 c (ждал завершения запроса)
ответ на медленный запрос: {"done":true}

cat > asgi_bad.py <<'PY'
"""ОШИБКА: свой обработчик перехватывает сигнал раньше сервера."""
import os
import signal
import sys

from fastapi import FastAPI

app = FastAPI()


def handle(signum, _frame):
    print("[мой обработчик] перехватил сигнал и завершаю немедленно", flush=True)
    sys.exit(0)      # сервер не успевает дозавершить запросы


signal.signal(signal.SIGTERM, handle)


@app.get("/slow")
async def slow():
    import asyncio
    await asyncio.sleep(5)
    return {"done": True}
PY

cat > Dockerfile.asgibad <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
RUN pip install --no-cache-dir "fastapi[standard]==0.141.1"
COPY asgi_bad.py /app/asgi_bad.py
WORKDIR /app
CMD ["fastapi", "run", "asgi_bad.py", "--port", "8000"]
EOF

docker build -q -f Dockerfile.asgibad -t sig:asgibad . > /dev/null
docker run -d --name bad-t -p 8102:8000 sig:asgibad > /dev/null
sleep 6
curl -s -m 10 localhost:8102/slow > /tmp/bad-result.txt 2>&1 &
CURL_PID=$!
sleep 1
docker stop --timeout 20 bad-t > /dev/null
wait $CURL_PID 2>/dev/null
echo -n "ответ на медленный запрос: "
[ -s /tmp/bad-result.txt ] && cat /tmp/bad-result.txt || echo "(пусто — соединение оборвано)"
echo
docker logs bad-t 2>&1 | grep 'мой обработчик'
docker rm bad-t > /dev/null; rm -f /tmp/bad-result.txt

ответ на медленный запрос: (пусто — соединение оборвано)
[мой обработчик] перехватил сигнал и завершаю немедленно

cd /tmp
docker rmi -f $(docker images -q --filter 'reference=sig:*') 2>/dev/null || true
rm -rf /tmp/pysig

mkdir -p /tmp/vsig && cd /tmp/vsig
cat > a.py <<'PY'
import signal, sys, time
r = True
def h(s, f):
    global r
    print("SIGTERM получен", flush=True); r = False
signal.signal(signal.SIGTERM, h)
print("старт", flush=True)
while r: time.sleep(0.2)
print("штатно", flush=True); sys.exit(0)
PY
printf 'FROM python:3.13-slim\nENV PYTHONUNBUFFERED=1\nCOPY a.py /a.py\nCMD ["python","/a.py"]\n' > Dockerfile
docker build -q -t vsig:1 . > /dev/null
docker run -d --name v vsig:1 > /dev/null; sleep 2
time docker stop v
docker inspect v --format 'код: {{.State.ExitCode}}'
docker logs v | tail -2
docker rm -f v > /dev/null; docker rmi vsig:1 > /dev/null; cd /tmp && rm -rf /tmp/vsig