Debian Codegraph @

upstream/debian-unstable/man3/sd_event_add_memory_pressure.3

raw
1 '\" t
2 .TH "SD_EVENT_ADD_MEMORY_PRESSURE" "3" "" "systemd 261~rc3" "sd_event_add_memory_pressure"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_event_add_memory_pressure, sd_event_source_set_memory_pressure_type, sd_event_source_set_memory_pressure_period, sd_event_trim_memory, sd_event_add_cpu_pressure, sd_event_source_set_cpu_pressure_type, sd_event_source_set_cpu_pressure_period, sd_event_add_io_pressure, sd_event_source_set_io_pressure_type, sd_event_source_set_io_pressure_period \- Add and configure an event source for memory, CPU, or IO pressure notifications
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-event\&.h>
29 .fi
30 .ft
31 .sp
32 .ft B
33 .nf
34 typedef struct sd_event_source sd_event_source;
35 .fi
36 .ft
37 .HP \w'int\ sd_event_add_memory_pressure('u
38 .BI "int sd_event_add_memory_pressure(sd_event\ *" "event" ", sd_event_source\ **" "ret_source" ", sd_event_handler_t\ " "handler" ", void\ *" "userdata" ");"
39 .HP \w'int\ sd_event_source_set_memory_pressure_type('u
40 .BI "int sd_event_source_set_memory_pressure_type(sd_event_source\ *" "source" ", const\ char\ *" "type" ");"
41 .HP \w'int\ sd_event_source_set_memory_pressure_period('u
42 .BI "int sd_event_source_set_memory_pressure_period(sd_event_source\ *" "source" ", uint64_t\ " "threshold_usec" ", uint64_t\ " "window_usec" ");"
43 .HP \w'int\ sd_event_add_cpu_pressure('u
44 .BI "int sd_event_add_cpu_pressure(sd_event\ *" "event" ", sd_event_source\ **" "ret_source" ", sd_event_handler_t\ " "handler" ", void\ *" "userdata" ");"
45 .HP \w'int\ sd_event_source_set_cpu_pressure_type('u
46 .BI "int sd_event_source_set_cpu_pressure_type(sd_event_source\ *" "source" ", const\ char\ *" "type" ");"
47 .HP \w'int\ sd_event_source_set_cpu_pressure_period('u
48 .BI "int sd_event_source_set_cpu_pressure_period(sd_event_source\ *" "source" ", uint64_t\ " "threshold_usec" ", uint64_t\ " "window_usec" ");"
49 .HP \w'int\ sd_event_add_io_pressure('u
50 .BI "int sd_event_add_io_pressure(sd_event\ *" "event" ", sd_event_source\ **" "ret_source" ", sd_event_handler_t\ " "handler" ", void\ *" "userdata" ");"
51 .HP \w'int\ sd_event_source_set_io_pressure_type('u
52 .BI "int sd_event_source_set_io_pressure_type(sd_event_source\ *" "source" ", const\ char\ *" "type" ");"
53 .HP \w'int\ sd_event_source_set_io_pressure_period('u
54 .BI "int sd_event_source_set_io_pressure_period(sd_event_source\ *" "source" ", uint64_t\ " "threshold_usec" ", uint64_t\ " "window_usec" ");"
55 .HP \w'int\ sd_event_trim_memory('u
56 .BI "int sd_event_trim_memory(void);"
57 .SH "DESCRIPTION"
58 .PP
59 \fBsd_event_add_memory_pressure()\fR
60 adds a new event source that is triggered whenever memory pressure is seen\&. Similarly,
61 \fBsd_event_add_cpu_pressure()\fR
62 and
63 \fBsd_event_add_io_pressure()\fR
64 add new event sources that are triggered whenever CPU or IO pressure is seen, respectively\&. This functionality is built around the Linux kernel\*(Aqs
65 \m[blue]\fBPressure Stall Information (PSI)\fR\m[]\&\s-2\u[1]\d\s+2
66 logic\&.
67 .PP
68 These functions expect an event loop object as first parameter, and return the allocated event source object in the second parameter, on success\&. The
69 \fIhandler\fR
70 parameter is a function to call when pressure is seen, or
71 \fBNULL\fR\&. The handler function will be passed the
72 \fIuserdata\fR
73 pointer, which may be chosen freely by the caller\&. The handler may return negative to signal an error (see below), other return values are ignored\&. If
74 \fIhandler\fR
75 is
76 \fBNULL\fR, a default handler is used\&. For
77 \fBsd_event_add_memory_pressure()\fR, the default handler compacts allocation caches maintained by
78 libsystemd
79 as well as glibc (via
80 \fBmalloc_trim\fR(3))\&. For
81 \fBsd_event_add_cpu_pressure()\fR
82 and
83 \fBsd_event_add_io_pressure()\fR, the default handler is a no\-op\&. It is recommended to pass a custom handler for CPU and IO pressure to take meaningful action when pressure is detected\&.
84 .PP
85 To destroy an event source object use
86 \fBsd_event_source_unref\fR(3), but note that the event source is only removed from the event loop when all references to the event source are dropped\&. To make sure an event source does not fire anymore, even if it is still referenced, disable the event source using
87 \fBsd_event_source_set_enabled\fR(3)
88 with
89 \fBSD_EVENT_OFF\fR\&.
90 .PP
91 If the second parameter of
92 \fBsd_event_add_memory_pressure()\fR,
93 \fBsd_event_add_cpu_pressure()\fR, or
94 \fBsd_event_add_io_pressure()\fR
95 is
96 \fBNULL\fR
97 no reference to the event source object is returned\&. In this case, the event source is considered "floating", and will be destroyed implicitly when the event loop itself is destroyed\&.
98 .PP
99 The memory pressure event source will fire according to the following logic:
100 .sp
101 .RS 4
102 .ie n \{\
103 \h'-04' 1.\h'+01'\c
104 .\}
105 .el \{\
106 .sp -1
107 .IP " 1." 4.2
108 .\}
109 If the
110 \fI$MEMORY_PRESSURE_WATCH\fR/\fI$MEMORY_PRESSURE_WRITE\fR
111 environment variables are set at the time the event source is established, it will watch the file, FIFO or AF_UNIX socket specified via
112 \fI$MEMORY_PRESSURE_WATCH\fR
113 (which must contain an absolute path name) for
114 \fBPOLLPRI\fR
115 (in case it is a regular file) or
116 \fBPOLLIN\fR
117 events (otherwise)\&. After opening the inode, it will write the (decoded) Base64 data provided via
118 \fI$MEMORY_PRESSURE_WRITE\fR
119 into it before it starts polling on it (the variable may be unset in which case this is skipped)\&. Typically, if used,
120 \fI$MEMORY_PRESSURE_WATCH\fR
121 will contain a path such as
122 /proc/pressure/memory
123 or a path to a specific
124 memory\&.pressure
125 file in the control group file system (cgroupfs)\&.
126 .RE
127 .sp
128 .RS 4
129 .ie n \{\
130 \h'-04' 2.\h'+01'\c
131 .\}
132 .el \{\
133 .sp -1
134 .IP " 2." 4.2
135 .\}
136 If these environment variables are not set, the local PSI interface file
137 memory\&.pressure
138 of the control group the invoking process is running in is used\&.
139 .RE
140 .sp
141 .RS 4
142 .ie n \{\
143 \h'-04' 3.\h'+01'\c
144 .\}
145 .el \{\
146 .sp -1
147 .IP " 3." 4.2
148 .\}
149 If that file does not exist, the system\-wide PSI interface file
150 /proc/pressure/memory
151 is watched instead\&.
152 .RE
153 .PP
154 The CPU pressure event source follows the same logic, but uses the
155 \fI$CPU_PRESSURE_WATCH\fR/\fI$CPU_PRESSURE_WRITE\fR
156 environment variables, the
157 cpu\&.pressure
158 cgroup file, and the system\-wide PSI interface file
159 /proc/pressure/cpu
160 instead\&. Note that
161 /proc/pressure/cpu
162 only provides the
163 "some"
164 line, not the
165 "full"
166 line, so only
167 "some"
168 is valid when watching at the system level\&.
169 .PP
170 The IO pressure event source follows the same logic, but uses the
171 \fI$IO_PRESSURE_WATCH\fR/\fI$IO_PRESSURE_WRITE\fR
172 environment variables, the
173 io\&.pressure
174 cgroup file, and the system\-wide PSI interface file
175 /proc/pressure/io
176 instead\&.
177 .PP
178 Or in other words: preferably any explicit configuration passed in by an invoking service manager (or similar) is used as notification source, before falling back to local notifications of the service, and finally to global notifications of the system\&.
179 .PP
180 Well\-behaving services and applications are recommended to react to memory pressure events by executing one or more of the following operations, in order to ensure optimal behaviour even on loaded and resource\-constrained systems:
181 .sp
182 .RS 4
183 .ie n \{\
184 \h'-04'\(bu\h'+03'\c
185 .\}
186 .el \{\
187 .sp -1
188 .IP \(bu 2.3
189 .\}
190 Release allocation caches such as
191 \fBmalloc_trim()\fR
192 or similar, both implemented in the libraries consumed by the program and in private allocation caches of the program itself\&.
193 .RE
194 .sp
195 .RS 4
196 .ie n \{\
197 \h'-04'\(bu\h'+03'\c
198 .\}
199 .el \{\
200 .sp -1
201 .IP \(bu 2.3
202 .\}
203 Release any other form of in\-memory caches that can easily be recovered if needed (e\&.g\&. browser caches)\&.
204 .RE
205 .sp
206 .RS 4
207 .ie n \{\
208 \h'-04'\(bu\h'+03'\c
209 .\}
210 .el \{\
211 .sp -1
212 .IP \(bu 2.3
213 .\}
214 Terminate idle worker threads or processes, or similar\&.
215 .RE
216 .sp
217 .RS 4
218 .ie n \{\
219 \h'-04'\(bu\h'+03'\c
220 .\}
221 .el \{\
222 .sp -1
223 .IP \(bu 2.3
224 .\}
225 Even exit entirely from the program if it is idle and can be automatically started when needed (for example via socket or bus activation)\&.
226 .RE
227 .PP
228 Any of the suggested operations should help easing memory pressure situations and allowing the system to make progress by reclaiming the memory for other purposes\&.
229 .PP
230 This event source typically fires on memory pressure stalls, i\&.e\&. when operational latency above a configured threshold already has been seen\&. This should be taken into consideration when discussing whether later latency to re\-acquire any released resources is acceptable: it is usually more important to think of the latencies that already happened than those coming up in future\&.
231 .PP
232 The
233 \fBsd_event_source_set_memory_pressure_type()\fR
234 and
235 \fBsd_event_source_set_memory_pressure_period()\fR
236 functions can be used to fine\-tune the PSI parameters for memory pressure notifications\&. The former takes either
237 "some",
238 "full"
239 as second parameter, the latter takes threshold and period times in microseconds as parameters\&. For details about these three parameters see the PSI documentation\&. Note that these two calls must be invoked immediately after allocating the event source, as they must be configured before polling begins\&. Also note that these calls will fail if memory pressure parameterization has been passed in via the
240 \fI$MEMORY_PRESSURE_WATCH\fR/\fI$MEMORY_PRESSURE_WRITE\fR
241 environment variables (or in other words: configuration supplied by a service manager wins over internal settings)\&.
242 .PP
243 Similarly,
244 \fBsd_event_source_set_cpu_pressure_type()\fR
245 and
246 \fBsd_event_source_set_cpu_pressure_period()\fR
247 can be used to fine\-tune the PSI parameters for CPU pressure notifications, and
248 \fBsd_event_source_set_io_pressure_type()\fR
249 and
250 \fBsd_event_source_set_io_pressure_period()\fR
251 can be used to fine\-tune the PSI parameters for IO pressure notifications\&. They work identically to their memory pressure counterparts\&. The type parameter takes either
252 "some"
253 or
254 "full", and the period function takes threshold and period times in microseconds\&. The same constraints apply: these calls must be invoked immediately after allocating the event source, and will fail if pressure parameterization has been passed in via the corresponding
255 \fI$*_PRESSURE_WATCH\fR/\fI$*_PRESSURE_WRITE\fR
256 environment variables\&.
257 .PP
258 The
259 \fBsd_event_trim_memory()\fR
260 function releases various internal allocation caches maintained by
261 libsystemd
262 and then invokes glibc\*(Aqs
263 \fBmalloc_trim\fR(3)\&. This makes the operation executed when the handler function parameter of
264 \fBsd_event_add_memory_pressure\fR
265 is passed as
266 \fBNULL\fR
267 directly accessible for invocation at any time (see above)\&. This function will log a structured log message at
268 \fBLOG_DEBUG\fR
269 level (with message ID f9b0be465ad540d0850ad32172d57c21) about the memory pressure operation\&.
270 .PP
271 For further details see
272 \m[blue]\fBResource Pressure Handling in systemd\fR\m[]\&\s-2\u[2]\d\s+2\&.
273 .SH "RETURN VALUE"
274 .PP
275 On success, these functions return 0 or a positive integer\&. On failure, they return a negative errno\-style error code\&.
276 .SS "Errors"
277 .PP
278 Returned errors may indicate the following problems:
279 .PP
280 \fB\-ENOMEM\fR
281 .RS 4
282 Not enough memory to allocate an object\&.
283 .sp
284 Added in version 254\&.
285 .RE
286 .PP
287 \fB\-EINVAL\fR
288 .RS 4
289 An invalid argument has been passed\&.
290 .sp
291 Added in version 254\&.
292 .RE
293 .PP
294 \fB\-EHOSTDOWN\fR
295 .RS 4
296 The
297 \fI$MEMORY_PRESSURE_WATCH\fR,
298 \fI$CPU_PRESSURE_WATCH\fR, or
299 \fI$IO_PRESSURE_WATCH\fR
300 variable has been set to the literal string
301 /dev/null, in order to explicitly disable pressure handling\&.
302 .sp
303 Added in version 254\&.
304 .RE
305 .PP
306 \fB\-EBADMSG\fR
307 .RS 4
308 The
309 \fI$MEMORY_PRESSURE_WATCH\fR,
310 \fI$CPU_PRESSURE_WATCH\fR, or
311 \fI$IO_PRESSURE_WATCH\fR
312 variable has been set to an invalid string, for example a relative rather than an absolute path\&.
313 .sp
314 Added in version 254\&.
315 .RE
316 .PP
317 \fB\-ENOTTY\fR
318 .RS 4
319 The
320 \fI$MEMORY_PRESSURE_WATCH\fR,
321 \fI$CPU_PRESSURE_WATCH\fR, or
322 \fI$IO_PRESSURE_WATCH\fR
323 variable points to a regular file outside of the procfs or cgroupfs file systems\&.
324 .sp
325 Added in version 254\&.
326 .RE
327 .PP
328 \fB\-EOPNOTSUPP\fR
329 .RS 4
330 No configuration via
331 \fI$MEMORY_PRESSURE_WATCH\fR,
332 \fI$CPU_PRESSURE_WATCH\fR, or
333 \fI$IO_PRESSURE_WATCH\fR
334 has been specified and the local kernel does not support the PSI interface\&.
335 .sp
336 Added in version 254\&.
337 .RE
338 .PP
339 \fB\-EBUSY\fR
340 .RS 4
341 This is returned by
342 \fBsd_event_source_set_memory_pressure_type()\fR,
343 \fBsd_event_source_set_memory_pressure_period()\fR,
344 \fBsd_event_source_set_cpu_pressure_type()\fR,
345 \fBsd_event_source_set_cpu_pressure_period()\fR,
346 \fBsd_event_source_set_io_pressure_type()\fR, and
347 \fBsd_event_source_set_io_pressure_period()\fR
348 if invoked on event sources at a time later than immediately after allocating them\&.
349 .sp
350 Added in version 254\&.
351 .RE
352 .PP
353 \fB\-ESTALE\fR
354 .RS 4
355 The event loop is already terminated\&.
356 .sp
357 Added in version 254\&.
358 .RE
359 .PP
360 \fB\-ECHILD\fR
361 .RS 4
362 The event loop has been created in a different process, library or module instance\&.
363 .sp
364 Added in version 254\&.
365 .RE
366 .PP
367 \fB\-EDOM\fR
368 .RS 4
369 The passed event source is not a signal event source\&.
370 .sp
371 Added in version 254\&.
372 .RE
373 .SH "NOTES"
374 .PP
375 Functions described here are available as a shared library, which can be compiled against and linked to with the
376 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
377 file\&.
378 .PP
379 The code described here uses
380 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
381 \fBsetenv\fR(3)
382 from a parallel thread\&. It is recommended to only do calls to
383 \fBsetenv()\fR
384 from an early phase of the program when no other threads have been started\&.
385 .SH "HISTORY"
386 .PP
387 \fBsd_event_add_memory_pressure()\fR,
388 \fBsd_event_source_set_memory_pressure_type()\fR,
389 \fBsd_event_source_set_memory_pressure_period()\fR, and
390 \fBsd_event_trim_memory()\fR
391 were added in version 254\&.
392 .PP
393 \fBsd_event_add_cpu_pressure()\fR,
394 \fBsd_event_source_set_cpu_pressure_type()\fR,
395 \fBsd_event_source_set_cpu_pressure_period()\fR,
396 \fBsd_event_add_io_pressure()\fR,
397 \fBsd_event_source_set_io_pressure_type()\fR, and
398 \fBsd_event_source_set_io_pressure_period()\fR
399 were added in version 261\&.
400 .SH "SEE ALSO"
401 .PP
402 \fBsystemd\fR(1), \fBsd-event\fR(3), \fBsd_event_new\fR(3), \fBsd_event_add_io\fR(3), \fBsd_event_add_time\fR(3), \fBsd_event_add_child\fR(3), \fBsd_event_add_inotify\fR(3), \fBsd_event_add_defer\fR(3), \fBsd_event_source_set_enabled\fR(3), \fBsd_event_source_set_description\fR(3), \fBsd_event_source_set_userdata\fR(3), \fBsd_event_source_set_floating\fR(3)
403 .SH "NOTES"
404 .IP " 1." 4
405 Pressure Stall Information (PSI)
406 .RS 4
407 \%https://docs.kernel.org/accounting/psi.html
408 .RE
409 .IP " 2." 4
410 Resource Pressure Handling in systemd
411 .RS 4
412 \%https://systemd.io/PRESSURE
413 .RE