sd_event_source_set_ratelimit_expire_callback(3)

1SD_EVENT_SOURCE_SET_RATELIsMdI_Te(v3e)nt_source_set_raStDe_lEiVmEiNtT_SOURCE_SET_RATELIMIT(3)
2
3
4

NAME

6       sd_event_source_set_ratelimit, sd_event_source_get_ratelimit,
7       sd_event_source_is_ratelimited,
8       sd_event_source_set_ratelimit_expire_callback,
9       sd_event_source_leave_ratelimit - Configure rate limiting on event
10       sources
11

SYNOPSIS

13       #include <systemd/sd-event.h>
14
15       int sd_event_source_set_ratelimit(sd_event_source *source,
16                                         uint64_t interval_usec,
17                                         unsigned burst);
18
19       int sd_event_source_get_ratelimit(sd_event_source *source,
20                                         uint64_t* ret_interval_usec,
21                                         unsigned* ret_burst);
22
23       int sd_event_source_is_ratelimited(sd_event_source *source);
24
25       int
26                                                         sd_event_source_set_ratelimit_expire_callback(sd_event_source *source,
27                                                         sd_event_handler_tcallback);
28
29       int sd_event_source_leave_ratelimit(sd_event_source *source);
30

DESCRIPTION

32       sd_event_source_set_ratelimit() may be used to enforce rate limiting on
33       an event source. When used an event source will be temporarily turned
34       off when it fires more often then a specified burst number within a
35       specified time interval. This is useful as simple mechanism to avoid
36       event source starvation if high priority event sources fire very
37       frequently.
38
39       Pass the event source to operate on as first argument, a time interval
40       in microseconds as second argument and a maximum dispatch limit
41       ("burst") as third parameter. Whenever the event source is dispatched
42       more often than the specified burst within the specified interval it is
43       placed in a mode similar to being disabled with
44       sd_event_source_set_enabled(3) and the SD_EVENT_OFF parameter. However
45       it is disabled only temporarily – once the specified interval is over
46       regular operation resumes. It is again disabled temporarily once the
47       specified rate limiting is hit the next time. If either the interval or
48       the burst value are specified as zero, rate limiting is turned off. By
49       default event sources do not have rate limiting enabled. Note that rate
50       limiting and disabling via sd_event_source_set_enabled() are
51       independent of each other, and an event source will only effect event
52       loop wake-ups and is dispatched while it both is enabled and rate
53       limiting is not in effect.
54
55       sd_event_source_get_ratelimit() may be used to query the current rate
56       limiting parameters set on the event source object source. The
57       previously set interval and burst vales are returned in the second and
58       third argument.
59
60       sd_event_source_is_ratelimited() may be used to query whether the event
61       source is currently affected by rate limiting, i.e. it has recently hit
62       the rate limit and is currently temporarily disabled due to that.
63
64       sd_event_source_set_ratelimit_expire_callback() may be used to set a
65       callback function that is invoked every time the event source leaves
66       rate limited state. Note that function is called in the same event loop
67       iteration in which state transition occurred.
68
69       sd_event_source_leave_ratelimit() may be used to immediately reenable
70       an event source that was temporarily disabled due to rate limiting.
71       This will reset the ratelimit counters for the current time interval.
72
73       Rate limiting is currently implemented for I/O, timer, signal, defer
74       and inotify event sources.
75

RETURN VALUE

77       On success, sd_event_source_set_ratelimit(),
78       sd_event_source_set_ratelimit_expire_callback and
79       sd_event_source_get_ratelimit() return a non-negative integer. On
80       failure, they return a negative errno-style error code.
81       sd_event_source_is_ratelimited() returns zero if rate limiting is
82       currently not in effect and greater than zero if it is in effect; it
83       returns a negative errno-style error code on failure.
84       sd_event_source_leave_ratelimit() returns zero if rate limiting wasn't
85       in effect on the specified event source, and positive if it was and
86       rate limiting is now turned off again; it returns a negative
87       errno-style error code on failure.
88
89   Errors
90       Returned errors may indicate the following problems:
91
92       -EINVAL
93           source is not a valid pointer to an sd_event_source object.
94
95       -ECHILD
96           The event loop has been created in a different process, library or
97           module instance.
98
99       -EDOM
100           It was attempted to use the rate limiting feature on an event
101           source type that does not support rate limiting.
102
103       -ENOEXEC
104           sd_event_source_get_ratelimit() was called on an event source that
105           doesn't have rate limiting configured.
106

NOTES

108       Functions described here are available as a shared library, which can
109       be compiled against and linked to with the libsystemd pkg-config(1)
110       file.
111
112       The code described here uses getenv(3), which is declared to be not
113       multi-thread-safe. This means that the code calling the functions
114       described here must not call setenv(3) from a parallel thread. It is
115       recommended to only do calls to setenv() from an early phase of the
116       program when no other threads have been started.
117

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

SEE ALSO