From 35b2028315f38f90ffdff83a680ae471ac221e34 Mon Sep 17 00:00:00 2001
From: tomershafir <tomer.shafir8@gmail.com>
Date: Sat, 19 Oct 2024 15:58:48 +0300
Subject: [PATCH] signal.md: describe auto signal handling

Add documentation about the default Seastar signal handlers and `app_template::config::auto_handle_sigint_sigterm` flag to `doc/signal.md`, as introducery information.
---
 doc/signal.md | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/doc/signal.md b/doc/signal.md
index d47696ca59..3b16f9ad45 100644
--- a/doc/signal.md
+++ b/doc/signal.md
@@ -2,11 +2,31 @@
 
 Seastar provides an interface to handle signals natively and safely as asynchronous tasks.
 
-It provides a dedicated header called [seastar/core/signal.hh](../include/seastar/core/signal.hh).
+## Default Signal Handlers
 
-## Usage
+Seastar sets by default signal handlers for SIGINT/SIGTERM that call reactor::stop(). The reactor will then execute callbacks installed by reactor::at_exit().
 
-You should call `seastar::handle_signal` procedure in order to register the provided signal handler for the specified signal based on the configuration params.
+You can disable this behavior, by setting `app_template::config::auto_handle_sigint_sigterm` to false. This flag is provided in the header [seastar/core/app-template.hh](../include/seastar/core/app-template..hh). Then, Seastar will not set signal handlers, and the default behavior of the Linux kernel will be preserved (terminate the program).
+
+### Examples
+
+```C++
+#include <seastar/core/app-template.hh>
+
+int main(int ac, char** av) {
+    seastar::app_template::config cfg;
+    cfg.auto_handle_sigint_sigterm = false;
+    seastar::app_template app(std::move(cfg));
+
+    return app.run(argc, argv, [] {
+        std::cout << "SIGINT/SIGTERM will terminate the program\n";
+    });
+}
+```
+
+## Custom Signal Handler
+
+In order to set a custom signal handler, Seastar provides a procedure called `seastar::handle_signal` in the header [seastar/core/signal.hh](../include/seastar/core/signal.hh). It registers a custom handler for the specified signal based on the configuration params.
 
 The procedure must be called inside the `app.run()` lambda, otherwise it's UB.