diff options
author | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2018-06-06 11:07:02 +0200 |
---|---|---|
committer | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2018-06-06 23:01:57 +0200 |
commit | fa17b4e8d93c715793e35242829b33fef54bddea (patch) | |
tree | 714dbc997b8217ccdeadf1964e2a4a8846b2f810 /man | |
parent | e3736e02231dd71b6674091b4db79e2dee800bca (diff) | |
download | systemd-fa17b4e8d93c715793e35242829b33fef54bddea.tar.gz |
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.
Diffstat (limited to 'man')
-rw-r--r-- | man/rules/meson.build | 4 | ||||
-rw-r--r-- | man/sd_bus_slot_set_destroy_callback.xml | 105 | ||||
-rw-r--r-- | man/sd_bus_slot_set_floating.xml | 1 |
3 files changed, 110 insertions, 0 deletions
diff --git a/man/rules/meson.build b/man/rules/meson.build index e1e2c5e60d..efbd940fe0 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -231,6 +231,10 @@ manpages = [ ['sd_bus_set_connected_signal', '3', ['sd_bus_get_connected_signal'], ''], ['sd_bus_set_sender', '3', ['sd_bus_get_sender'], ''], ['sd_bus_set_watch_bind', '3', ['sd_bus_get_watch_bind'], ''], + ['sd_bus_slot_set_destroy_callback', + '3', + ['sd_bus_slot_get_destroy_callback'], + ''], ['sd_bus_slot_set_floating', '3', ['sd_bus_slot_get_floating'], ''], ['sd_bus_track_add_name', '3', diff --git a/man/sd_bus_slot_set_destroy_callback.xml b/man/sd_bus_slot_set_destroy_callback.xml new file mode 100644 index 0000000000..6334444f9a --- /dev/null +++ b/man/sd_bus_slot_set_destroy_callback.xml @@ -0,0 +1,105 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<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> + + <refpurpose>Define the callback function for resource cleanup.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></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> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <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 specified as an argument to the constuctor functions, see + <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + or directly, see + <citerefentry><refentrytitle>sd_bus_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This callback function is called even if <parameter>userdata</parameter> is + <constant>NULL</constant>.</para> + + <para><function>sd_bus_slot_get_destroy_callback()</function> returns the current callback + for <parameter>slot</parameter> in the <parameter>callback</parameter> parameter.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_slot_set_destroy_callback()</function> returns 0 or a + positive integer. On failure, it returns a negative errno-style error code.</para> + + <para><function>sd_bus_slot_get_destroy_callback()</function> returns 1 if the destroy callback + function is set, 0 if not. On failure, it returns a negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The <parameter>slot</parameter> parameter is <constant>NULL</constant>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_slot_set_floating.xml b/man/sd_bus_slot_set_floating.xml index cae1f5353c..650b56f8c2 100644 --- a/man/sd_bus_slot_set_floating.xml +++ b/man/sd_bus_slot_set_floating.xml @@ -110,6 +110,7 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_slot_set_destroy_callback</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> |