man: document the new sd_bus_slot_set_floating() call

Also extend the memory management description of sd-bus highlighting the
effect of "floating" slot objects a bit.

1 files changed, 20 insertions, 15 deletions

diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml
index f36272e854..da06fb9cbf 100644
--- a/man/sd_bus_default.xml
+++ b/man/sd_bus_default.xml
@@ -206,21 +206,26 @@
     <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     to drop the reference.</para>
 
-    <para>Queued but unwritten/unread messages also keep a reference
-    to their bus connection object. For this reason, even if an
-    application dropped all references to a bus connection, it might
-    not get destroyed right away. Until all incoming queued
-    messages are read, and until all outgoing unwritten messages are
-    written, the bus object will stay
-    alive. <function>sd_bus_flush()</function> may be used to write
-    all outgoing queued messages so they drop their references. To
-    flush the unread incoming messages, use
-    <function>sd_bus_close()</function>, which will also close the bus
-    connection. When using the default bus logic, it is a good idea to
-    first invoke <function>sd_bus_flush()</function> followed by
-    <function>sd_bus_close()</function> when a thread or process
-    terminates, and thus its bus connection object should be
-    freed.</para>
+    <para>Queued but unwritten/unread messages keep a reference to their bus connection object. For this reason, even
+    if an application dropped all references to a bus connection, it might not get destroyed right away. Until all
+    incoming queued messages are read, and until all outgoing unwritten messages are written, the bus object will stay
+    alive. <function>sd_bus_flush()</function> may be used to write all outgoing queued messages so they drop their
+    references. To flush the unread incoming messages, use <function>sd_bus_close()</function>, which will also close
+    the bus connection. When using the default bus logic, it is a good idea to first invoke
+    <function>sd_bus_flush()</function> followed by <function>sd_bus_close()</function> when a thread or process
+    terminates, and thus its bus connection object should be freed.</para>
+
+    <para>Normally, slot objects (as created by
+    <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> and similar
+    calls) keep a reference to their bus connection object, too. Thus, as long as a bus slot object remains referenced
+    its bus object will remain allocated too. Optionally, bus slot objects may be placed in "floating" mode. When in
+    floating mode the life cycle of the bus slot object is bound to the bus object, i.e. when the bus object is freed
+    the bus slot object is automatically unreferenced too. The floating state of a slot object may be controlled
+    explicitly with
+    <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    though usually floating bus slot objects are created by passing <constant>NULL</constant> as the
+    <parameter>slot</parameter> parameter of <function>sd_bus_add_match()</function> and related calls, thus indicating
+    that the caller is not directly interested in referencing and managing the bus slot object.</para>
 
     <para>The life cycle of the default bus connection should be the
     responsibility of the code that creates/owns the thread the