docs: add note in flux_signal_watcher_create(3)

garlick · garlick · commit 17e1b1fef163 · 2025-01-09T09:11:47.000-08:00
Problem: signals should generally only be handled in the main thread
of a multi-threaded program, but this is undocumented.

Add a note to the signal watcher man page.
diff --git a/doc/man3/flux_signal_watcher_create.rst b/doc/man3/flux_signal_watcher_create.rst
@@ -37,6 +37,10 @@ When one :var:`callback` is shared by multiple watchers, the signal number that
 triggered the event can be obtained with
 :func:`flux_signal_watcher_get_signum`.
 
+Signal handling can be tricky in multi-threaded programs.  It is advisable
+to handle signals in the main thread only.  For example, block signals by
+calling :linux:man2:`sigprocmask` before spawning other threads, and register
+signal watchers only in the main thread.
 
 RETURN VALUE
 ============
diff --git a/doc/test/spell.en.pws b/doc/test/spell.en.pws
@@ -940,3 +940,4 @@ cPATH
 SATTR
 myprogram
 unref
+sigprocmask
