man: sd_unref does not necessarily free the bus

Document that sd_unref() does not necessarily free the bus,
even if no part of the program explicitly refs it, due to
the queued messages.

diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml
index 95b347bdfdbcec7d6b7b2afdbd1ac4b24eb405ea..782dfb57069cbf4328eeaca2c8bfb560826ffeab 100644 (file)
--- a/man/sd_bus_default.xml
+++ b/man/sd_bus_default.xml
@@ -219,6 +219,12 @@
     one. Use
     <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     to drop the reference.</para>
+
+    <para>Queued messages also keep a reference to the bus. For this reason, just
+    because no application is having a reference to the bus does not mean that
+    the bus object will be destroyed. Until all the messages are sent, the bus object
+    will stay alive. <function>sd_bus_flush</function> can be used to send all the
+    queued messages so they drop their references.</para>
   </refsect1>
 
   <refsect1>

diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml
index 44744a00292d9d0415432e64f3a6a8d789a70505..aff2ed2e8395b2fae3821e58bbf139bae3c251af 100644 (file)
--- a/man/sd_bus_new.xml
+++ b/man/sd_bus_new.xml
@@ -77,8 +77,8 @@
     <para><function>sd_bus_new()</function> creates a new bus
     object. This object is reference-counted, and will be destroyed
     when all references are gone. Initially, the caller of this
-    function owns the sole reference. The bus object will not be
-    connected to any bus initially. To connect it to a bus, make sure
+    function owns the sole reference and the bus object will not be
+    connected to any bus. To connect it to a bus, make sure
     to set an address with
     <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     or a related call, and then start the connection with
@@ -94,15 +94,13 @@
     well-known bus in a single function invocation.</para>
 
     <para><function>sd_bus_ref()</function> creates a new reference to
-    <parameter>bus</parameter>. This bus object will not be destroyed
-    until <function>sd_bus_unref()</function> has been called as many
-    times plus once more. Once the reference count has dropped to
-    zero, <parameter>bus</parameter> cannot be used anymore, so
-    further calls to <function>sd_bus_ref()</function> or
-    <function>sd_bus_unref()</function> are illegal.</para>
+    <parameter>bus</parameter>.</para>
 
     <para><function>sd_bus_unref()</function> destroys a reference to
-    <parameter>bus</parameter>.</para>
+    <parameter>bus</parameter>. Once the reference count has dropped
+    to zero, <parameter>bus</parameter> cannot be used anymore, so
+    further calls to <function>sd_bus_ref()</function> or
+    <function>sd_bus_unref()</function> are illegal.</para>
   </refsect1>
 
   <refsect1>