minor symfony#15535 [Messenger] Supervisor graceful shutdown (AymDev)

javiereguiluz · javiereguiluz · commit 07f41f705916 · 2021-07-20T15:34:27.000+02:00
This PR was squashed before being merged into the 4.4 branch. Discussion ---------- [Messenger] Supervisor graceful shutdown >[Messenger] Add details on graceful shutdown Added a section to Messenger's documentation on the workers SIGTERM signal handling when the pcntl extension is installed. I'm making this PR because I struggled to perform a graceful shutdown as described in symfony/symfony#41906 and I think this could help other users in the future. This is my first contribution, I'd be happy to rework anything which doesn't meet the documentation standards. Commits ------- 79d5a07 [Messenger] Supervisor graceful shutdown
diff --git a/messenger.rst b/messenger.rst
@@ -653,6 +653,25 @@ config and start your workers:
 
 See the `Supervisor docs`_ for more details.
 
+Graceful Shutdown
+~~~~~~~~~~~~~~~~~
+
+Workers can handle the ``SIGTERM`` POSIX signal to finish handling their
+current message before exiting, as long as the `PCNTL`_ extension is installed.
+
+.. tip::
+
+    In some cases the ``SIGTERM`` signal is sent by Supervisor itself (e.g.
+    stopping a Docker container having Supervisor as its entrypoint).
+    In these cases you need to add a ``stopwaitsecs`` key to the program
+    configuration (with a value of the desired grace period in seconds)
+    in order to perform a graceful shutdown.
+    
+    .. code-block:: ini
+    
+        [program:x]
+        stopwaitsecs=20
+
 .. _messenger-retries-failures:
 
 Retries & Failures
@@ -1747,4 +1766,5 @@ Learn more
 .. _`Enqueue's transport`: https://github.com/sroze/messenger-enqueue-transport
 .. _`streams`: https://redis.io/topics/streams-intro
 .. _`Supervisor docs`: http://supervisord.org/
+.. _`PCNTL`: https://www.php.net/manual/book.pcntl.php
 .. _`SymfonyCasts' message serializer tutorial`: https://symfonycasts.com/screencast/messenger/transport-serializer
