man/sd_event_source_set_ratelimit.xml

   1 <?xml version='1.0'?>
   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 -->
   5
   6 <refentry id="sd_event_source_set_ratelimit" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_event_source_set_ratelimit</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_event_source_set_ratelimit</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>sd_event_source_set_ratelimit</refname>
  20     <refname>sd_event_source_get_ratelimit</refname>
  21     <refname>sd_event_source_is_ratelimited</refname>
  22     <refname>sd_event_source_set_ratelimit_expire_callback</refname>
  23     <refname>sd_event_source_leave_ratelimit</refname>
  24
  25     <refpurpose>Configure rate limiting on event sources</refpurpose>
  26   </refnamediv>
  27
  28   <refsynopsisdiv>
  29     <funcsynopsis>
  30       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  31
  32       <funcprototype>
  33         <funcdef>int <function>sd_event_source_set_ratelimit</function></funcdef>
  34         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  35         <paramdef>uint64_t <parameter>interval_usec</parameter></paramdef>
  36         <paramdef>unsigned <parameter>burst</parameter></paramdef>
  37       </funcprototype>
  38
  39       <funcprototype>
  40         <funcdef>int <function>sd_event_source_get_ratelimit</function></funcdef>
  41         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  42         <paramdef>uint64_t* <parameter>ret_interval_usec</parameter></paramdef>
  43         <paramdef>unsigned* <parameter>ret_burst</parameter></paramdef>
  44       </funcprototype>
  45
  46       <funcprototype>
  47         <funcdef>int <function>sd_event_source_is_ratelimited</function></funcdef>
  48         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  49       </funcprototype>
  50
  51       <funcprototype>
  52         <funcdef>int <function>sd_event_source_set_ratelimit_expire_callback</function></funcdef>
  53         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  54         <paramdef>sd_event_handler_t<parameter>callback</parameter></paramdef>
  55       </funcprototype>
  56
  57       <funcprototype>
  58         <funcdef>int <function>sd_event_source_leave_ratelimit</function></funcdef>
  59         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  60       </funcprototype>
  61     </funcsynopsis>
  62   </refsynopsisdiv>
  63
  64   <refsect1>
  65     <title>Description</title>
  66
  67     <para><function>sd_event_source_set_ratelimit()</function> may be used to enforce rate limiting on an
  68     event source. When used an event source will be temporarily turned off when it fires more often then a
  69     specified burst number within a specified time interval. This is useful as simple mechanism to avoid
  70     event source starvation if high priority event sources fire very frequently.</para>
  71
  72     <para>Pass the event source to operate on as first argument, a time interval in microseconds as second
  73     argument and a maximum dispatch limit ("burst") as third parameter. Whenever the event source is
  74     dispatched more often than the specified burst within the specified interval it is placed in a mode
  75     similar to being disabled with
  76     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  77     and the <constant>SD_EVENT_OFF</constant> parameter. However it is disabled only temporarily – once the
  78     specified interval is over regular operation resumes. It is again disabled temporarily once the specified rate
  79     limiting is hit the next time. If either the interval or the burst value are specified as zero, rate
  80     limiting is turned off. By default event sources do not have rate limiting enabled. Note that rate
  81     limiting and disabling via <function>sd_event_source_set_enabled()</function> are independent of each
  82     other, and an event source will only effect event loop wake-ups and is dispatched while it both is
  83     enabled and rate limiting is not in effect.</para>
  84
  85     <para><function>sd_event_source_get_ratelimit()</function> may be used to query the current rate limiting
  86     parameters set on the event source object <parameter>source</parameter>. The previously set interval and
  87     burst vales are returned in the second and third argument.</para>
  88
  89     <para><function>sd_event_source_is_ratelimited()</function> may be used to query whether the event source
  90     is currently affected by rate limiting, i.e. it has recently hit the rate limit and is currently
  91     temporarily disabled due to that.</para>
  92
  93     <para><function>sd_event_source_set_ratelimit_expire_callback()</function> may be used to set a callback
  94     function that is invoked every time the event source leaves rate limited state. Note that function is
  95     called in the same event loop iteration in which state transition occurred.</para>
  96
  97     <para><function>sd_event_source_leave_ratelimit()</function> may be used to immediately reenable an event
  98     source that was temporarily disabled due to rate limiting. This will reset the ratelimit counters for the
  99     current time interval.</para>
 100
 101     <para>Rate limiting is currently implemented for I/O, timer, signal, defer and inotify event
 102     sources.</para>
 103   </refsect1>
 104
 105   <refsect1>
 106     <title>Return Value</title>
 107
 108     <para>On success, <function>sd_event_source_set_ratelimit()</function>,
 109     <function>sd_event_source_set_ratelimit_expire_callback</function> and
 110     <function>sd_event_source_get_ratelimit()</function> return a non-negative integer. On failure, they
 111     return a negative errno-style error code. <function>sd_event_source_is_ratelimited()</function> returns
 112     zero if rate limiting is currently not in effect and greater than zero if it is in effect; it returns a
 113     negative errno-style error code on failure. <function>sd_event_source_leave_ratelimit()</function>
 114     returns zero if rate limiting wasn't in effect on the specified event source, and positive if it was and
 115     rate limiting is now turned off again; it returns a negative errno-style error code on failure.</para>
 116
 117     <refsect2>
 118       <title>Errors</title>
 119
 120       <para>Returned errors may indicate the following problems:</para>
 121
 122       <variablelist>
 123         <varlistentry>
 124           <term><constant>-EINVAL</constant></term>
 125
 126           <listitem><para><parameter>source</parameter> is not a valid pointer to an
 127           <structname>sd_event_source</structname> object.
 128           </para>
 129
 130           <xi:include href="version-info.xml" xpointer="v248"/></listitem>
 131         </varlistentry>
 132
 133         <varlistentry>
 134           <term><constant>-ECHILD</constant></term>
 135
 136           <listitem><para>The event loop has been created in a different process, library or module instance.</para>
 137
 138           <xi:include href="version-info.xml" xpointer="v248"/></listitem>
 139         </varlistentry>
 140
 141         <varlistentry>
 142           <term><constant>-EDOM</constant></term>
 143
 144           <listitem><para>It was attempted to use the rate limiting feature on an event source type that does
 145           not support rate limiting.</para>
 146
 147           <xi:include href="version-info.xml" xpointer="v248"/></listitem>
 148         </varlistentry>
 149
 150         <varlistentry>
 151           <term><constant>-ENOEXEC</constant></term>
 152
 153           <listitem><para><function>sd_event_source_get_ratelimit()</function> was called on an event source
 154           that doesn't have rate limiting configured.</para>
 155
 156           <xi:include href="version-info.xml" xpointer="v248"/></listitem>
 157         </varlistentry>
 158
 159       </variablelist>
 160     </refsect2>
 161   </refsect1>
 162
 163   <xi:include href="libsystemd-pkgconfig.xml" />
 164
 165   <refsect1>
 166     <title>History</title>
 167     <para><function>sd_event_source_set_ratelimit()</function>,
 168     <function>sd_event_source_get_ratelimit()</function>, and
 169     <function>sd_event_source_is_ratelimited()</function> were added in version 248.</para>
 170     <para><function>sd_event_source_set_ratelimit_expire_callback()</function> was added in version 250.</para>
 171     <para><function>sd_event_source_leave_ratelimit()</function> was added in version 254.</para>
 172   </refsect1>
 173
 174   <refsect1>
 175     <title>See Also</title>
 176
 177     <para><simplelist type="inline">
 178       <member><citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 179       <member><citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 180       <member><citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 181       <member><citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 182       <member><citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 183       <member><citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 184       <member><citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 185     </simplelist></para>
 186   </refsect1>
 187
 188 </refentry>