sd-event: add sd_event_source_disable_unref() helper

man/rules/meson.build

@@ -445,7 +445,9 @@ manpages = [
  ['sd_event_source_set_userdata', '3', ['sd_event_source_get_userdata'], ''],
  ['sd_event_source_unref',
   '3',
-  ['sd_event_source_ref', 'sd_event_source_unrefp'],
+  ['sd_event_source_disable_unref',
+   'sd_event_source_ref',
+   'sd_event_source_unrefp'],
   ''],
  ['sd_event_wait',
   '3',

man/sd_event_source_unref.xml

@@ -19,6 +19,7 @@
     <refname>sd_event_source_unref</refname>
     <refname>sd_event_source_unrefp</refname>
     <refname>sd_event_source_ref</refname>
+    <refname>sd_event_source_disable_unref</refname>
 
     <refpurpose>Increase or decrease event source reference counters</refpurpose>
   </refnamediv>
@@ -42,6 +43,10 @@
         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>sd_event_source* <function>sd_event_source_disable_unref</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+      </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
 
@@ -77,23 +82,26 @@
     the passed event source object is
     <constant>NULL</constant>.</para>
 
-    <para>Note that event source objects stay alive and may be
+    <para>Note that event source objects stay alive and may be dispatched as long as they have a reference
-    dispatched as long as they have a reference counter greater than
+    counter greater than zero. In order to drop a reference of an event source and make sure the associated
-    zero. In order to drop a reference of an event source and make
+    event source handler function is not called anymore it is recommended to combine a call of
-    sure the associated event source handler function is not called
-    anymore it is recommended to combine a call of
     <function>sd_event_source_unref()</function> with a prior call to
-    <function>sd_event_source_set_enabled()</function> with
+    <function>sd_event_source_set_enabled()</function> with <constant>SD_EVENT_OFF</constant> or call
-    <constant>SD_EVENT_OFF</constant>.</para>
+    <function>sd_event_source_disable_unref()</function>, see below.</para>
+
+    <para><function>sd_event_source_disable_unref()</function> combines a call to
+    <function>sd_event_source_set_enabled()</function> with <constant>SD_EVENT_OFF</constant> with
+    <function>sd_event_source_unref()</function>. This ensures that the source is disabled before the local
+    reference to it is lost. The <parameter>source</parameter> parameter is allowed to be
+    <constant>NULL</constant>.</para>
   </refsect1>
 
   <refsect1>
     <title>Return Value</title>
 
-    <para><function>sd_event_source_unref()</function> always returns
+    <para><function>sd_event_source_unref()</function> and
-    <constant>NULL</constant>.
+    <function>sd_event_source_disable_unref()</function> always return <constant>NULL</constant>.
-    <function>sd_event_source_ref()</function> always returns the
+    <function>sd_event_source_ref()</function> always returns the event source object passed in.</para>
-    event source object passed in.</para>
   </refsect1>
 
   <xi:include href="libsystemd-pkgconfig.xml" />

src/libsystemd/libsystemd.sym

@@ -680,4 +680,5 @@ global:
 LIBSYSTEMD_243 {
 global:
         sd_bus_object_vtable_format;
+        sd_event_source_disable_unref;
 } LIBSYSTEMD_241;

src/libsystemd/sd-event/sd-event.c

@@ -339,6 +339,12 @@ fail:
 
 DEFINE_PUBLIC_TRIVIAL_REF_UNREF_FUNC(sd_event, sd_event, event_free);
 
+_public_ sd_event_source* sd_event_source_disable_unref(sd_event_source *s) {
+        if (s)
+                (void) sd_event_source_set_enabled(s, SD_EVENT_OFF);
+        return sd_event_source_unref(s);
+}
+
 static bool event_pid_changed(sd_event *e) {
         assert(e);
 

src/systemd/sd-event.h

@@ -113,6 +113,7 @@ int sd_event_get_iteration(sd_event *e, uint64_t *ret);
 
 sd_event_source* sd_event_source_ref(sd_event_source *s);
 sd_event_source* sd_event_source_unref(sd_event_source *s);
+sd_event_source* sd_event_source_disable_unref(sd_event_source *s);
 
 sd_event *sd_event_source_get_event(sd_event_source *s);
 void* sd_event_source_get_userdata(sd_event_source *s);