From 910c6ada40c175f85a7fb1ff6e65221f1cd36cc3 Mon Sep 17 00:00:00 2001 From: Tanmoy Sarkar Date: Fri, 12 Jun 2026 23:30:48 +0530 Subject: [PATCH] docs(companion): Document USR2 reexec limitation Hot reexec runs old and new masters concurrently, so each runs its own companion manager and every companion runs twice -- harmful for singletons like a scheduler. Document the limitation and the SIGHUP alternative. Co-Authored-By: Claude Opus 4.8 (1M context) --- gunicorn/companion/README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/gunicorn/companion/README.md b/gunicorn/companion/README.md index 84e28f1b..99873ab1 100644 --- a/gunicorn/companion/README.md +++ b/gunicorn/companion/README.md @@ -134,3 +134,13 @@ restarts the manager with the reloaded config. | `control.py` | Unix socket server and JSON framing | | `ctl.py` | `gunicorn-companion` command-line client | +## Limitations + +Hot reexec (`SIGUSR2` zero-downtime upgrade) is not supported with +companions. During the overlap the old and new masters each run their own +companion manager, so every companion runs twice. For singletons such as a +scheduler this means duplicate work (e.g. double-fired jobs). Stop and +restart the master instead of reexec'ing when companions are configured, or +keep singleton companions out of the companion set. A graceful reload +(`SIGHUP`) is fine: it restarts the single manager in place. +