diff options
Diffstat (limited to 'man/sd_bus_default.xml')
| -rw-r--r-- | man/sd_bus_default.xml | 74 |
1 files changed, 22 insertions, 52 deletions
diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml index 62520ff4dd..53cc9d7768 100644 --- a/man/sd_bus_default.xml +++ b/man/sd_bus_default.xml @@ -4,39 +4,13 @@ <!-- SPDX-License-Identifier: LGPL-2.1+ - - This file is part of systemd. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="sd_bus_default"> +<refentry id="sd_bus_default" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_default</title> <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -219,21 +193,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 @@ -289,16 +268,7 @@ by returned. See <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> </refsect1> - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_open_user()</function> and the other - functions described here are available as a shared library, which - can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry - project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> + <xi:include href="libsystemd-pkgconfig.xml" /> <refsect1> <title>See Also</title> |