2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6 <refentry id=
"sd_event_source_unref" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
9 <title>sd_event_source_unref
</title>
10 <productname>systemd
</productname>
14 <refentrytitle>sd_event_source_unref
</refentrytitle>
15 <manvolnum>3</manvolnum>
19 <refname>sd_event_source_unref
</refname>
20 <refname>sd_event_source_unrefp
</refname>
21 <refname>sd_event_source_ref
</refname>
22 <refname>sd_event_source_disable_unref
</refname>
23 <refname>sd_event_source_disable_unrefp
</refname>
25 <refpurpose>Increase or decrease event source reference counters
</refpurpose>
30 <funcsynopsisinfo>#include
<systemd/sd-event.h
></funcsynopsisinfo>
33 <funcdef>sd_event_source*
<function>sd_event_source_unref
</function></funcdef>
34 <paramdef>sd_event_source *
<parameter>source
</parameter></paramdef>
38 <funcdef>void
<function>sd_event_source_unrefp
</function></funcdef>
39 <paramdef>sd_event_source **
<parameter>source
</parameter></paramdef>
43 <funcdef>sd_event_source*
<function>sd_event_source_ref
</function></funcdef>
44 <paramdef>sd_event_source *
<parameter>source
</parameter></paramdef>
48 <funcdef>sd_event_source*
<function>sd_event_source_disable_unref
</function></funcdef>
49 <paramdef>sd_event_source *
<parameter>source
</parameter></paramdef>
53 <funcdef>void
<function>sd_event_source_disable_unrefp
</function></funcdef>
54 <paramdef>sd_event_source **
<parameter>source
</parameter></paramdef>
60 <title>Description
</title>
62 <para><function>sd_event_source_unref()
</function> may be used to decrement by one the internal reference
63 counter of the event source object specified as
<parameter>source
</parameter>. The reference counter is
64 initially set to one, when the event source is created with calls such as
65 <citerefentry><refentrytitle>sd_event_add_io
</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
66 <citerefentry><refentrytitle>sd_event_add_time
</refentrytitle><manvolnum>3</manvolnum></citerefentry>. When
67 the reference counter reaches zero, the object is detached from the event loop object and destroyed.
70 <para><function>sd_event_source_unrefp()
</function> is similar to
71 <function>sd_event_source_unref()
</function> but takes a pointer to a
72 pointer to an
<type>sd_event_source
</type> object. This call is useful in
73 conjunction with GCC's and LLVM's
<ulink
74 url=
"https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
75 Variable Attribute
</ulink>. Note that this function is defined as
76 inline function.
</para>
78 <para><function>sd_event_source_ref()
</function> may be used to increase by one the internal reference
79 counter of the event source object specified as
<parameter>source
</parameter>.
</para>
81 <para><function>sd_event_source_unref()
</function>,
82 <function>sd_bus_creds_unrefp()
</function> and
83 <function>sd_bus_creds_ref()
</function> execute no operation if
84 the passed event source object is
85 <constant>NULL
</constant>.
</para>
87 <para>Note that event source objects stay alive and may be dispatched as long as they have a reference
88 counter greater than zero. In order to drop a reference of an event source and make sure the associated
89 event source handler function is not called anymore it is recommended to combine a call of
90 <function>sd_event_source_unref()
</function> with a prior call to
91 <function>sd_event_source_set_enabled()
</function> with
<constant>SD_EVENT_OFF
</constant> or call
92 <function>sd_event_source_disable_unref()
</function>, see below.
</para>
94 <para><function>sd_event_source_disable_unref()
</function> combines a call to
95 <function>sd_event_source_set_enabled()
</function> with
<constant>SD_EVENT_OFF
</constant> with
96 <function>sd_event_source_unref()
</function>. This ensures that the source is disabled before the local
97 reference to it is lost. The
<parameter>source
</parameter> parameter is allowed to be
98 <constant>NULL
</constant>.
</para>
100 <para><function>sd_event_source_disable_unrefp()
</function> is similar to
101 <function>sd_event_source_unrefp()
</function>, but in addition disables the source first. This call is
102 useful in conjunction with GCC's and LLVM's
103 <ulink url=
"https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up Variable
104 Attribute
</ulink>. Note that this function is defined as inline function.
</para>
108 <title>Return Value
</title>
110 <para><function>sd_event_source_unref()
</function> and
111 <function>sd_event_source_disable_unref()
</function> always return
<constant>NULL
</constant>.
112 <function>sd_event_source_ref()
</function> always returns the event source object passed in.
</para>
115 <xi:include href=
"libsystemd-pkgconfig.xml" />
118 <title>History
</title>
119 <para><function>sd_event_source_unref()
</function>,
120 <function>sd_event_source_unrefp()
</function>, and
121 <function>sd_event_source_ref()
</function> were added in version
229.
</para>
122 <para><function>sd_event_source_disable_unref()
</function> and
123 <function>sd_event_source_disable_unrefp()
</function> were added in version
243.
</para>
127 <title>See Also
</title>
129 <para><simplelist type=
"inline">
130 <member><citerefentry><refentrytitle>sd-event
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
131 <member><citerefentry><refentrytitle>sd_event_add_io
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
132 <member><citerefentry><refentrytitle>sd_event_add_time
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
133 <member><citerefentry><refentrytitle>sd_event_add_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
134 <member><citerefentry><refentrytitle>sd_event_add_child
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
135 <member><citerefentry><refentrytitle>sd_event_add_inotify
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
136 <member><citerefentry><refentrytitle>sd_event_add_defer
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
137 <member><citerefentry><refentrytitle>sd_event_source_set_enabled
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>