diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml
index 782dfb5706..1cf2cb8f9a 100644
--- a/man/sd_bus_default.xml
+++ b/man/sd_bus_default.xml
@@ -111,9 +111,9 @@
sd_bus_default() acquires a bus
connection object to the user bus when invoked in user context, or
to the system bus otherwise. The connection object is associated
- to the calling thread. Each time the function is invoked from the
- same thread the same object is returned, but its reference count
- is increased by one, as long as at least one reference is
+ with the calling thread. Each time the function is invoked from
+ the same thread the same object is returned, but its reference
+ count is increased by one, as long as at least one reference is
kept. When the last reference to the connection is dropped (using
the
sd_bus_unref3
@@ -121,10 +121,11 @@
not automatically terminated when the associated thread ends. It
is important to drop the last reference to the bus connection
explicitly before the thread ends or otherwise the connection will
- be leaked.
+ be leaked. Also, queued but unread or unwritten messages keep the
+ bus referenced, see below.
sd_bus_default_user() returns a user
- bus connection object associated to the calling thread.
+ bus connection object associated with the calling thread.
sd_bus_default_system() is similar, but
connects to the system bus. Note that
sd_bus_default() is identical to these two
@@ -192,14 +193,6 @@
-
- Return Value
-
- On success, these calls return 0 or a positive
- integer. On failure, these calls return a negative
- errno-style error code.
-
-
Reference ownership
The functions sd_bus_open(),
@@ -207,24 +200,57 @@
sd_bus_open_system(),
sd_bus_open_system_remote(), and
sd_bus_open_system_machine() return a new
- object and the caller owns the sole reference. When not needed
- anymore, this reference should be destroyed with
+ connection object and the caller owns the sole reference. When not
+ needed anymore, this reference should be destroyed with
sd_bus_unref3.
The functions sd_bus_default(),
sd_bus_default_user() and
sd_bus_default_system() do not necessarily
- create a new object, but increase the connection reference by
- one. Use
+ create a new object, but increase the connection reference of an
+ existing connection object by one. Use
sd_bus_unref3
to drop the reference.
- 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. sd_bus_flush can be used to send all the
- queued messages so they drop their references.
+ 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. sd_bus_flush() may be used to write
+ all outgoing queued messages so they drop their references. To
+ flush the unread incoming messages use
+ sd_bus_close(), which will also close the bus
+ connection. When using the default bus logic it is a good idea to
+ first invoke sd_bus_flush() followed by
+ sd_bus_close() when a thread or process
+ terminates, and thus its bus connection object should be
+ freed.
+
+ The life-cycle of the default bus connection should be the
+ responsibility of the code that creates/owns the thread the
+ default bus connection object is associated with. Library code
+ should neither call sd_bus_flush() nor
+ sd_bus_close() on default bus objects unless
+ it does so in its own private, self-allocated thread. Library code
+ should not use the default bus object in other threads unless it
+ is clear that the program using it will life-cycle the bus
+ connection object and flush and close it before exiting from the
+ thread. In libraries where it is not clear that the calling
+ program will life-cycle the bus connection object it is hence
+ recommended to use sd_bus_open_system()
+ instead of sd_bus_default_system() and
+ related calls.
+
+
+
+ Return Value
+
+ On success, these calls return 0 or a positive
+ integer. On failure, these calls return a negative
+ errno-style error code.