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 - Configure rate limiting
9       on event sources
10

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

70       On success, sd_event_source_set_ratelimit(),
71       sd_event_source_set_ratelimit_expire_callback and
72       sd_event_source_get_ratelimit() return a non-negative integer. On
73       failure, they return a negative errno-style error code.
74       sd_event_source_is_ratelimited returns zero if rate limiting is
75       currently not in effect and greater than zero if it is in effect; it
76       returns a negative errno-style error code on failure.
77
78   Errors
79       Returned errors may indicate the following problems:
80
81       -EINVAL
82           source is not a valid pointer to an sd_event_source object.
83
84       -ECHILD
85           The event loop has been created in a different process.
86
87       -EDOM
88           It was attempted to use the rate limiting feature on an event
89           source type that does not support rate limiting.
90
91       -ENOEXEC
92           sd_event_source_get_ratelimit() was called on an event source that
93           doesn't have rate limiting configured.
94

NOTES

96       These APIs are implemented as a shared library, which can be compiled
97       and linked to with the libsystemd pkg-config(1) file.
98

SEE ALSO

100       sd-event(3), sd_event_add_io(3), sd_event_add_time(3),
101       sd_event_add_signal(3), sd_event_add_inotify(3), sd_event_add_defer(3),
102       sd_event_source_set_enabled(3)
103
104
105
106systemd 253                                   SD_EVENT_SOURCE_SET_RATELIMIT(3)
Impressum