Merge pull request #2052 from poettering/export-cleanup

Make gcc cleanup helper calls public in most of our sd-xyz APIs

1 files changed, 29 insertions, 2 deletions

diff --git a/man/sd_event_new.xml b/man/sd_event_new.xml
index 3356faa899..2c23b00a8c 100644
--- a/man/sd_event_new.xml
+++ b/man/sd_event_new.xml
@@ -47,6 +47,7 @@
     <refname>sd_event_default</refname>
     <refname>sd_event_ref</refname>
     <refname>sd_event_unref</refname>
+    <refname>sd_event_unrefp</refname>
     <refname>sd_event_get_tid</refname>
     <refname>sd_event</refname>
 
@@ -80,6 +81,11 @@
       </funcprototype>
 
       <funcprototype>
+        <funcdef>void <function>sd_event_unrefp</function></funcdef>
+        <paramdef>sd_event **<parameter>event</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
         <funcdef>int <function>sd_event_get_tid</function></funcdef>
         <paramdef>sd_event *<parameter>event</parameter></paramdef>
         <paramdef>pid_t *<parameter>tid</parameter></paramdef>
@@ -139,8 +145,29 @@
     all remaining event sources of the event loop also need to be
     freed as each keeps a reference to it.</para>
 
-    <para>Both <function>sd_event_ref()</function> and
-    <function>sd_event_unref()</function> execute no operation if the
+    <para><function>sd_event_unrefp()</function> is similar to
+    <function>sd_event_unref()</function> but takes a pointer to a
+    pointer to an <type>sd_event</type> object. This call is useful in
+    conjunction with GCC's and LLVM's <ulink
+    url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
+    Variable Attribute</ulink>. Note that this function is defined as
+    inline function. Use a declaration like the following,
+    in order to allocate an event loop object that is freed
+    automatically as the code block is left:</para>
+
+    <programlisting>{
+        __attribute__((cleanup(sd_event_unrefp)) sd_event *event = NULL;
+        int r;
+        …
+        r = sd_event_default(&amp;event);
+        if (r &lt; 0)
+                fprintf(stderr, "Failed to allocate event loop: %s\n", strerror(-r));
+        …
+}</programlisting>
+
+    <para><function>sd_event_ref()</function>,
+    <function>sd_event_unref()</function> and
+    <function>sd_event_unrefp()</function> execute no operation if the
     passed in event loop object is <constant>NULL</constant>.</para>
 
     <para><function>sd_event_get_tid()</function> retrieves the thread