sd-event: add an explicit API for leaving the ratelimit state

Sometimes, it might make sense to end the ratelimit window early.

2 files changed, 17 insertions, 5 deletions

diff --git a/man/rules/meson.build b/man/rules/meson.build
index 6bd54739af..d496ebc747 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -633,6 +633,7 @@ manpages = [
   '3',
   ['sd_event_source_get_ratelimit',
    'sd_event_source_is_ratelimited',
+   'sd_event_source_leave_ratelimit',
    'sd_event_source_set_ratelimit_expire_callback'],
   ''],
  ['sd_event_source_set_userdata', '3', ['sd_event_source_get_userdata'], ''],
diff --git a/man/sd_event_source_set_ratelimit.xml b/man/sd_event_source_set_ratelimit.xml
index 07ac18b791..89eb34fa9b 100644
--- a/man/sd_event_source_set_ratelimit.xml
+++ b/man/sd_event_source_set_ratelimit.xml
@@ -20,6 +20,7 @@
     <refname>sd_event_source_get_ratelimit</refname>
     <refname>sd_event_source_is_ratelimited</refname>
     <refname>sd_event_source_set_ratelimit_expire_callback</refname>
+    <refname>sd_event_source_leave_ratelimit</refname>
 
     <refpurpose>Configure rate limiting on event sources</refpurpose>
   </refnamediv>
@@ -53,6 +54,10 @@
         <paramdef>sd_event_handler_t<parameter>callback</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_leave_ratelimit</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+      </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
 
@@ -85,10 +90,14 @@
     is currently affected by rate limiting, i.e. it has recently hit the rate limit and is currently
     temporarily disabled due to that.</para>
 
-    <para><function>sd_event_source_set_ratelimit_expire_callback</function> may be used to set a callback
+    <para><function>sd_event_source_set_ratelimit_expire_callback()</function> may be used to set a callback
     function that is invoked every time the event source leaves rate limited state. Note that function is
     called in the same event loop iteration in which state transition occurred.</para>
 
+    <para><function>sd_event_source_leave_ratelimit()</function> may be used to immediately reenable an event
+    source that was temporarily disabled due to rate limiting. This will reset the ratelimit counters for the
+    current time interval.</para>
+
     <para>Rate limiting is currently implemented for I/O, timer, signal, defer and inotify event
     sources.</para>
   </refsect1>
@@ -98,10 +107,12 @@
 
     <para>On success, <function>sd_event_source_set_ratelimit()</function>,
     <function>sd_event_source_set_ratelimit_expire_callback</function> and
-    <function>sd_event_source_get_ratelimit()</function> return a non-negative integer. On failure, they return
-    a negative errno-style error code. <function>sd_event_source_is_ratelimited</function> returns zero if rate
-    limiting is currently not in effect and greater than zero if it is in effect; it returns a negative
-    errno-style error code on failure.</para>
+    <function>sd_event_source_get_ratelimit()</function> return a non-negative integer. On failure, they
+    return a negative errno-style error code. <function>sd_event_source_is_ratelimited()</function> returns
+    zero if rate limiting is currently not in effect and greater than zero if it is in effect; it returns a
+    negative errno-style error code on failure. <function>sd_event_source_leave_ratelimit()</function>
+    returns zero if rate limiting wasn't in effect on the specified event source, and positive if it was and
+    rate limiting is now turned off again; it returns a negative errno-style error code on failure.</para>
 
     <refsect2>
       <title>Errors</title>