From b9350e70aa050d97c47ff59994e84fa8c3de4738 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Fri, 2 Oct 2020 09:51:36 +0200
Subject: sd-event: support callback=NULL in IO/child/inotify/defer event
 sources, too

Also, document this functionality more prominently, including with a
reference from sd_event_exit().

This is mostly to make things complete, as previously we supported NULL
callbacks only in _add_time() and _add_signal(). However, I think this
makes snese for IO event sources too (think: when some fd such as a pipe
end sees SIGHUP or so, exit), as well as defer or post event sources (i.e. exit
once we got nothing else to do). This also adds support for inotify
event sources, simply to complete things (I can't see the immediate use,
but maybe someone else comes up with it).

The only event source type that doesn't allow callback=NULL now are exit
callbacks, but for them they make little sense, as the event loop is
exiting then anyway.
---
 man/sd_event_add_signal.xml | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

(limited to 'man/sd_event_add_signal.xml')

diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml
index 43794bd7ce..85de53120f 100644
--- a/man/sd_event_add_signal.xml
+++ b/man/sd_event_add_signal.xml
@@ -79,9 +79,7 @@
     threads before this function is called (using <citerefentry
     project='man-pages'><refentrytitle>sigprocmask</refentrytitle><manvolnum>2</manvolnum></citerefentry> or
     <citerefentry
-    project='man-pages'><refentrytitle>pthread_sigmask</refentrytitle><manvolnum>3</manvolnum></citerefentry>). If
-    the handler is not specified (<parameter>handler</parameter> is <constant>NULL</constant>), a default
-    handler which causes the program to exit cleanly will be used.</para>
+    project='man-pages'><refentrytitle>pthread_sigmask</refentrytitle><manvolnum>3</manvolnum></citerefentry>).</para>
 
     <para>By default, the event source is enabled permanently
     (<constant>SD_EVENT_ON</constant>), but this may be changed with
@@ -107,6 +105,12 @@
     "floating", and will be destroyed implicitly when the event loop
     itself is destroyed.</para>
 
+    <para>If the <parameter>handler</parameter> parameter to <function>sd_event_add_signal()</function> is
+    <constant>NULL</constant>, and the event source fires, this will be considered a request to exit the
+    event loop. In this case, the <parameter>userdata</parameter> parameter, cast to an integer, is passed as
+    the exit code parameter to
+    <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+
     <para><function>sd_event_source_get_signal()</function> returns
     the configured signal number of an event source created previously
     with <function>sd_event_add_signal()</function>. It takes the
-- 
cgit v1.2.1