shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-23 21:35:11 +03:00
Code
d0e11b9e17
systemd/man/sd_bus_slot_set_destroy_callback.xml

140 lines
6.4 KiB
XML
Raw Normal View History

man: drop mode line in file headers This is already included in .dir-locals, so we don't need it in the files themselves.
2018-07-03 00:15:39 +03:00
<?xml version='1.0'?>
man: use same header for all files The "include" files had type "book" for some raeason. I don't think this is meaningful. Let's just use the same everywhere. $ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
2019-03-14 16:40:58 +03:00
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
man: use same version in public and system ident.
2023-12-25 17:48:33 +03:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
license: LGPL-2.1+ -> LGPL-2.1-or-later
2020-11-09 07:23:58 +03:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
bus: optionally call a callbacks for cleanup This adds a function sd_bus_slot_set_destroy_callback() to set a function which can free userdata or perform other cleanups. sd_bus_slot_get_destory_callback() queries the callback, and is included for completeness. Without something like this, for floating asynchronous callbacks, which might be called or not, depending on the sequence of events, it's hard to perform resource cleanup. The alternative would be to always perform the cleanup from the caller too, but that requires more coordination and keeping of some shared state. It's nicer to keep the cleanup contained between the callback and the function that requests the callback.
2018-06-06 12:07:02 +03:00
<refentry id="sd_bus_slot_set_destroy_callback"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_bus_slot_set_destroy_callback</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>sd_bus_slot_set_destroy_callback</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_bus_slot_set_destroy_callback</refname>
<refname>sd_bus_slot_get_destroy_callback</refname>
sd-bus: also add destroy callbacks to sd_bus_track objects This augments previous work for this for sd_bus_slot objects, and adds the same concept to sd_bus_track objects, too.
2018-06-07 13:29:52 +03:00
<refname>sd_bus_track_set_destroy_callback</refname>
<refname>sd_bus_track_get_destroy_callback</refname>
<refname>sd_bus_destroy_t</refname>
bus: optionally call a callbacks for cleanup This adds a function sd_bus_slot_set_destroy_callback() to set a function which can free userdata or perform other cleanups. sd_bus_slot_get_destory_callback() queries the callback, and is included for completeness. Without something like this, for floating asynchronous callbacks, which might be called or not, depending on the sequence of events, it's hard to perform resource cleanup. The alternative would be to always perform the cleanup from the caller too, but that requires more coordination and keeping of some shared state. It's nicer to keep the cleanup contained between the callback and the function that requests the callback.
2018-06-06 12:07:02 +03:00
tree-wide: fixes for assorted grammar and spelling issues Fixes #16363. Also includes some changes where I generalized the pattern.
2020-07-06 11:49:59 +03:00
<refpurpose>Define the callback function for resource cleanup</refpurpose>
bus: optionally call a callbacks for cleanup This adds a function sd_bus_slot_set_destroy_callback() to set a function which can free userdata or perform other cleanups. sd_bus_slot_get_destory_callback() queries the callback, and is included for completeness. Without something like this, for floating asynchronous callbacks, which might be called or not, depending on the sequence of events, it's hard to perform resource cleanup. The alternative would be to always perform the cleanup from the caller too, but that requires more coordination and keeping of some shared state. It's nicer to keep the cleanup contained between the callback and the function that requests the callback.
2018-06-06 12:07:02 +03:00
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>typedef int (*<function>sd_bus_destroy_t</function>)</funcdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_slot_set_destroy_callback</function></funcdef>
<paramdef>sd_bus_slot *<parameter>slot</parameter></paramdef>
<paramdef>sd_bus_destroy_t <parameter>callback</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_slot_get_destroy_callback</function></funcdef>
<paramdef>sd_bus_slot *<parameter>slot</parameter></paramdef>
<paramdef>sd_bus_destroy_t *<parameter>callback</parameter></paramdef>
</funcprototype>
sd-bus: also add destroy callbacks to sd_bus_track objects This augments previous work for this for sd_bus_slot objects, and adds the same concept to sd_bus_track objects, too.
2018-06-07 13:29:52 +03:00
<funcprototype>
<funcdef>int <function>sd_bus_track_set_destroy_callback</function></funcdef>
<paramdef>sd_bus_track *<parameter>track</parameter></paramdef>
<paramdef>sd_bus_destroy_t <parameter>callback</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_track_get_destroy_callback</function></funcdef>
<paramdef>sd_bus_track *<parameter>track</parameter></paramdef>
<paramdef>sd_bus_destroy_t *<parameter>callback</parameter></paramdef>
</funcprototype>
bus: optionally call a callbacks for cleanup This adds a function sd_bus_slot_set_destroy_callback() to set a function which can free userdata or perform other cleanups. sd_bus_slot_get_destory_callback() queries the callback, and is included for completeness. Without something like this, for floating asynchronous callbacks, which might be called or not, depending on the sequence of events, it's hard to perform resource cleanup. The alternative would be to always perform the cleanup from the caller too, but that requires more coordination and keeping of some shared state. It's nicer to keep the cleanup contained between the callback and the function that requests the callback.
2018-06-06 12:07:02 +03:00
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
sd-bus: also add destroy callbacks to sd_bus_track objects This augments previous work for this for sd_bus_slot objects, and adds the same concept to sd_bus_track objects, too.
2018-06-07 13:29:52 +03:00
<para><function>sd_bus_slot_set_destroy_callback()</function> sets <parameter>callback</parameter> as the callback
function to be called right before the bus slot object <parameter>slot</parameter> is deallocated. The
<parameter>userdata</parameter> pointer from the slot object will be passed as the <parameter>userdata</parameter>
parameter. This pointer can be set by an argument to the constructor functions, see
<citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, or directly,
see <citerefentry><refentrytitle>sd_bus_slot_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
This callback function is called even if <parameter>userdata</parameter> is <constant>NULL</constant>. Note that
this callback is invoked at a time where the bus slot object itself is already invalidated, and executing
operations or taking new references to the bus slot object is not permissible.</para>
bus: optionally call a callbacks for cleanup This adds a function sd_bus_slot_set_destroy_callback() to set a function which can free userdata or perform other cleanups. sd_bus_slot_get_destory_callback() queries the callback, and is included for completeness. Without something like this, for floating asynchronous callbacks, which might be called or not, depending on the sequence of events, it's hard to perform resource cleanup. The alternative would be to always perform the cleanup from the caller too, but that requires more coordination and keeping of some shared state. It's nicer to keep the cleanup contained between the callback and the function that requests the callback.
2018-06-06 12:07:02 +03:00
<para><function>sd_bus_slot_get_destroy_callback()</function> returns the current callback
for <parameter>slot</parameter> in the <parameter>callback</parameter> parameter.</para>
sd-bus: also add destroy callbacks to sd_bus_track objects This augments previous work for this for sd_bus_slot objects, and adds the same concept to sd_bus_track objects, too.
2018-06-07 13:29:52 +03:00
<para><function>sd_bus_track_set_destroy_callback()</function> and
man: add missing parentheses
2018-06-29 06:40:27 +03:00
<function>sd_bus_track_get_destroy_callback()</function> provide equivalent functionality for the
sd-bus: also add destroy callbacks to sd_bus_track objects This augments previous work for this for sd_bus_slot objects, and adds the same concept to sd_bus_track objects, too.
2018-06-07 13:29:52 +03:00
<parameter>userdata</parameter> pointer associated with bus peer tracking objects. For details about bus peer
tracking objects, see
<citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
bus: optionally call a callbacks for cleanup This adds a function sd_bus_slot_set_destroy_callback() to set a function which can free userdata or perform other cleanups. sd_bus_slot_get_destory_callback() queries the callback, and is included for completeness. Without something like this, for floating asynchronous callbacks, which might be called or not, depending on the sequence of events, it's hard to perform resource cleanup. The alternative would be to always perform the cleanup from the caller too, but that requires more coordination and keeping of some shared state. It's nicer to keep the cleanup contained between the callback and the function that requests the callback.
2018-06-06 12:07:02 +03:00
</refsect1>
<refsect1>
<title>Return Value</title>
sd-bus: also add destroy callbacks to sd_bus_track objects This augments previous work for this for sd_bus_slot objects, and adds the same concept to sd_bus_track objects, too.
2018-06-07 13:29:52 +03:00
<para>On success, <function>sd_bus_slot_set_destroy_callback()</function> and
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 16:53:00 +03:00
<function>sd_bus_track_set_destroy_callback()</function> return 0 or a positive integer. On failure, they
return a negative errno-style error code.</para>
bus: optionally call a callbacks for cleanup This adds a function sd_bus_slot_set_destroy_callback() to set a function which can free userdata or perform other cleanups. sd_bus_slot_get_destory_callback() queries the callback, and is included for completeness. Without something like this, for floating asynchronous callbacks, which might be called or not, depending on the sequence of events, it's hard to perform resource cleanup. The alternative would be to always perform the cleanup from the caller too, but that requires more coordination and keeping of some shared state. It's nicer to keep the cleanup contained between the callback and the function that requests the callback.
2018-06-06 12:07:02 +03:00
sd-bus: also add destroy callbacks to sd_bus_track objects This augments previous work for this for sd_bus_slot objects, and adds the same concept to sd_bus_track objects, too.
2018-06-07 13:29:52 +03:00
<para><function>sd_bus_slot_get_destroy_callback()</function> and
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 16:53:00 +03:00
<function>sd_bus_track_get_destroy_callback()</function> return positive if the destroy callback function
is set, 0 if not. On failure, they return a negative errno-style error code.</para>
bus: optionally call a callbacks for cleanup This adds a function sd_bus_slot_set_destroy_callback() to set a function which can free userdata or perform other cleanups. sd_bus_slot_get_destory_callback() queries the callback, and is included for completeness. Without something like this, for floating asynchronous callbacks, which might be called or not, depending on the sequence of events, it's hard to perform resource cleanup. The alternative would be to always perform the cleanup from the caller too, but that requires more coordination and keeping of some shared state. It's nicer to keep the cleanup contained between the callback and the function that requests the callback.
2018-06-06 12:07:02 +03:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 16:53:00 +03:00
<refsect2>
<title>Errors</title>
bus: optionally call a callbacks for cleanup This adds a function sd_bus_slot_set_destroy_callback() to set a function which can free userdata or perform other cleanups. sd_bus_slot_get_destory_callback() queries the callback, and is included for completeness. Without something like this, for floating asynchronous callbacks, which might be called or not, depending on the sequence of events, it's hard to perform resource cleanup. The alternative would be to always perform the cleanup from the caller too, but that requires more coordination and keeping of some shared state. It's nicer to keep the cleanup contained between the callback and the function that requests the callback.
2018-06-06 12:07:02 +03:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 16:53:00 +03:00
<para>Returned errors may indicate the following problems:</para>
bus: optionally call a callbacks for cleanup This adds a function sd_bus_slot_set_destroy_callback() to set a function which can free userdata or perform other cleanups. sd_bus_slot_get_destory_callback() queries the callback, and is included for completeness. Without something like this, for floating asynchronous callbacks, which might be called or not, depending on the sequence of events, it's hard to perform resource cleanup. The alternative would be to always perform the cleanup from the caller too, but that requires more coordination and keeping of some shared state. It's nicer to keep the cleanup contained between the callback and the function that requests the callback.
2018-06-06 12:07:02 +03:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 16:53:00 +03:00
<variablelist>
<varlistentry>
<term><constant>-EINVAL</constant></term>
bus: optionally call a callbacks for cleanup This adds a function sd_bus_slot_set_destroy_callback() to set a function which can free userdata or perform other cleanups. sd_bus_slot_get_destory_callback() queries the callback, and is included for completeness. Without something like this, for floating asynchronous callbacks, which might be called or not, depending on the sequence of events, it's hard to perform resource cleanup. The alternative would be to always perform the cleanup from the caller too, but that requires more coordination and keeping of some shared state. It's nicer to keep the cleanup contained between the callback and the function that requests the callback.
2018-06-06 12:07:02 +03:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 16:53:00 +03:00
<listitem><para>The <parameter>slot</parameter> or <parameter>track</parameter> parameter is
<constant>NULL</constant>.</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
bus: optionally call a callbacks for cleanup This adds a function sd_bus_slot_set_destroy_callback() to set a function which can free userdata or perform other cleanups. sd_bus_slot_get_destory_callback() queries the callback, and is included for completeness. Without something like this, for floating asynchronous callbacks, which might be called or not, depending on the sequence of events, it's hard to perform resource cleanup. The alternative would be to always perform the cleanup from the caller too, but that requires more coordination and keeping of some shared state. It's nicer to keep the cleanup contained between the callback and the function that requests the callback.
2018-06-06 12:07:02 +03:00
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
man: add version information for functions
2023-09-04 15:46:35 +03:00
<refsect1>
<title>History</title>
man: condense version information for functions Use a more compact form like 'a, b, and c were added in version x'
2023-09-18 19:44:26 +03:00
<para><function>sd_bus_destroy_t()</function>,
<function>sd_bus_slot_set_destroy_callback()</function>,
<function>sd_bus_slot_get_destroy_callback()</function>,
<function>sd_bus_track_set_destroy_callback()</function>, and
<function>sd_bus_track_get_destroy_callback()</function> were added in version 239.</para>
man: add version information for functions
2023-09-04 15:46:35 +03:00
</refsect1>
bus: optionally call a callbacks for cleanup This adds a function sd_bus_slot_set_destroy_callback() to set a function which can free userdata or perform other cleanups. sd_bus_slot_get_destory_callback() queries the callback, and is included for completeness. Without something like this, for floating asynchronous callbacks, which might be called or not, depending on the sequence of events, it's hard to perform resource cleanup. The alternative would be to always perform the cleanup from the caller too, but that requires more coordination and keeping of some shared state. It's nicer to keep the cleanup contained between the callback and the function that requests the callback.
2018-06-06 12:07:02 +03:00
<refsect1>
<title>See Also</title>
man: use <simplelist> for 'See also' sections This is just a slight markup improvement; there should be no difference in rendering.
2023-12-22 21:09:32 +03:00
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_bus_slot_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_bus_track_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
</simplelist></para>
bus: optionally call a callbacks for cleanup This adds a function sd_bus_slot_set_destroy_callback() to set a function which can free userdata or perform other cleanups. sd_bus_slot_get_destory_callback() queries the callback, and is included for completeness. Without something like this, for floating asynchronous callbacks, which might be called or not, depending on the sequence of events, it's hard to perform resource cleanup. The alternative would be to always perform the cleanup from the caller too, but that requires more coordination and keeping of some shared state. It's nicer to keep the cleanup contained between the callback and the function that requests the callback.
2018-06-06 12:07:02 +03:00
</refsect1>
</refentry>
Copy Permalink