Debian Codegraph @

upstream/debian-trixie/man3/sd_event_add_memory_pressure.3

raw
1 '\" t
2 .TH "SD_EVENT_ADD_MEMORY_PRESSURE" "3" "" "systemd 257.13" "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 \- Add and configure an event source run as result of memory pressure
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_trim_memory('u
44 .BI "int sd_event_trim_memory(void);"
45 .SH "DESCRIPTION"
46 .PP
47 \fBsd_event_add_memory_pressure()\fR
48 adds a new event source that is triggered whenever memory pressure is seen\&. This functionality is built around the Linux kernel\*(Aqs
49 \m[blue]\fBPressure Stall Information (PSI)\fR\m[]\&\s-2\u[1]\d\s+2
50 logic\&.
51 .PP
52 Expects an event loop object as first parameter, and returns the allocated event source object in the second parameter, on success\&. The
53 \fIhandler\fR
54 parameter is a function to call when memory pressure is seen, or
55 \fBNULL\fR\&. The handler function will be passed the
56 \fIuserdata\fR
57 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
58 \fIhandler\fR
59 is
60 \fBNULL\fR, a default handler that compacts allocation caches maintained by
61 libsystemd
62 as well as glibc (via
63 \fBmalloc_trim\fR(3)) will be used\&.
64 .PP
65 To destroy an event source object use
66 \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
67 \fBsd_event_source_set_enabled\fR(3)
68 with
69 \fBSD_EVENT_OFF\fR\&.
70 .PP
71 If the second parameter of
72 \fBsd_event_add_memory_pressure()\fR
73 is
74 \fBNULL\fR
75 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\&.
76 .PP
77 The event source will fire according to the following logic:
78 .sp
79 .RS 4
80 .ie n \{\
81 \h'-04' 1.\h'+01'\c
82 .\}
83 .el \{\
84 .sp -1
85 .IP " 1." 4.2
86 .\}
87 If the
88 \fI$MEMORY_PRESSURE_WATCH\fR/\fI$MEMORY_PRESSURE_WRITE\fR
89 environment variables are set at the time the event source is established, it will watch the file, FIFO or AF_UNIX socket specified via
90 \fI$MEMORY_PRESSURE_WATCH\fR
91 (which must contain an absolute path name) for
92 \fBPOLLPRI\fR
93 (in case it is a regular file) or
94 \fBPOLLIN\fR
95 events (otherwise)\&. After opening the inode, it will write the (decoded) Base64 data provided via
96 \fI$MEMORY_PRESSURE_WRITE\fR
97 into it before it starts polling on it (the variable may be unset in which case this is skipped)\&. Typically, if used,
98 \fI$MEMORY_PRESSURE_WATCH\fR
99 will contain a path such as
100 /proc/pressure/memory
101 or a path to a specific
102 memory\&.pressure
103 file in the control group file system (cgroupfs)\&.
104 .RE
105 .sp
106 .RS 4
107 .ie n \{\
108 \h'-04' 2.\h'+01'\c
109 .\}
110 .el \{\
111 .sp -1
112 .IP " 2." 4.2
113 .\}
114 If these environment variables are not set, the local PSI interface file
115 memory\&.pressure
116 of the control group the invoking process is running in is used\&.
117 .RE
118 .sp
119 .RS 4
120 .ie n \{\
121 \h'-04' 3.\h'+01'\c
122 .\}
123 .el \{\
124 .sp -1
125 .IP " 3." 4.2
126 .\}
127 If that file does not exist, the system\-wide PSI interface file
128 /proc/pressure/memory
129 is watched instead\&.
130 .RE
131 .PP
132 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\&.
133 .PP
134 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:
135 .sp
136 .RS 4
137 .ie n \{\
138 \h'-04'\(bu\h'+03'\c
139 .\}
140 .el \{\
141 .sp -1
142 .IP \(bu 2.3
143 .\}
144 Release allocation caches such as
145 \fBmalloc_trim()\fR
146 or similar, both implemented in the libraries consumed by the program and in private allocation caches of the program itself\&.
147 .RE
148 .sp
149 .RS 4
150 .ie n \{\
151 \h'-04'\(bu\h'+03'\c
152 .\}
153 .el \{\
154 .sp -1
155 .IP \(bu 2.3
156 .\}
157 Release any other form of in\-memory caches that can easily be recovered if needed (e\&.g\&. browser caches)\&.
158 .RE
159 .sp
160 .RS 4
161 .ie n \{\
162 \h'-04'\(bu\h'+03'\c
163 .\}
164 .el \{\
165 .sp -1
166 .IP \(bu 2.3
167 .\}
168 Terminate idle worker threads or processes, or similar\&.
169 .RE
170 .sp
171 .RS 4
172 .ie n \{\
173 \h'-04'\(bu\h'+03'\c
174 .\}
175 .el \{\
176 .sp -1
177 .IP \(bu 2.3
178 .\}
179 Even exit entirely from the program if it is idle and can be automatically started when needed (for example via socket or bus activation)\&.
180 .RE
181 .PP
182 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\&.
183 .PP
184 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\&.
185 .PP
186 The
187 \fBsd_event_source_set_memory_pressure_type()\fR
188 and
189 \fBsd_event_source_set_memory_pressure_period()\fR
190 functions can be used to fine\-tune the PSI parameters for pressure notifications\&. The former takes either
191 "some",
192 "full"
193 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
194 \fI$MEMORY_PRESSURE_WATCH\fR/\fI$MEMORY_PRESSURE_WRITE\fR
195 environment variables (or in other words: configuration supplied by a service manager wins over internal settings)\&.
196 .PP
197 The
198 \fBsd_event_trim_memory()\fR
199 function releases various internal allocation caches maintained by
200 libsystemd
201 and then invokes glibc\*(Aqs
202 \fBmalloc_trim\fR(3)\&. This makes the operation executed when the handler function parameter of
203 \fBsd_event_add_memory_pressure\fR
204 is passed as
205 \fBNULL\fR
206 directly accessible for invocation at any time (see above)\&. This function will log a structured log message at
207 \fBLOG_DEBUG\fR
208 level (with message ID f9b0be465ad540d0850ad32172d57c21) about the memory pressure operation\&.
209 .PP
210 For further details see
211 \m[blue]\fBMemory Pressure Handling in systemd\fR\m[]\&\s-2\u[2]\d\s+2\&.
212 .SH "RETURN VALUE"
213 .PP
214 On success, these functions return 0 or a positive integer\&. On failure, they return a negative errno\-style error code\&.
215 .SS "Errors"
216 .PP
217 Returned errors may indicate the following problems:
218 .PP
219 \fB\-ENOMEM\fR
220 .RS 4
221 Not enough memory to allocate an object\&.
222 .sp
223 Added in version 254\&.
224 .RE
225 .PP
226 \fB\-EINVAL\fR
227 .RS 4
228 An invalid argument has been passed\&.
229 .sp
230 Added in version 254\&.
231 .RE
232 .PP
233 \fB\-EHOSTDOWN\fR
234 .RS 4
235 The
236 \fI$MEMORY_PRESSURE_WATCH\fR
237 variable has been set to the literal string
238 /dev/null, in order to explicitly disable memory pressure handling\&.
239 .sp
240 Added in version 254\&.
241 .RE
242 .PP
243 \fB\-EBADMSG\fR
244 .RS 4
245 The
246 \fI$MEMORY_PRESSURE_WATCH\fR
247 variable has been set to an invalid string, for example a relative rather than an absolute path\&.
248 .sp
249 Added in version 254\&.
250 .RE
251 .PP
252 \fB\-ENOTTY\fR
253 .RS 4
254 The
255 \fI$MEMORY_PRESSURE_WATCH\fR
256 variable points to a regular file outside of the procfs or cgroupfs file systems\&.
257 .sp
258 Added in version 254\&.
259 .RE
260 .PP
261 \fB\-EOPNOTSUPP\fR
262 .RS 4
263 No configuration via
264 \fI$MEMORY_PRESSURE_WATCH\fR
265 has been specified and the local kernel does not support the PSI interface\&.
266 .sp
267 Added in version 254\&.
268 .RE
269 .PP
270 \fB\-EBUSY\fR
271 .RS 4
272 This is returned by
273 \fBsd_event_source_set_memory_pressure_type()\fR
274 and
275 \fBsd_event_source_set_memory_pressure_period()\fR
276 if invoked on event sources at a time later than immediately after allocating them\&.
277 .sp
278 Added in version 254\&.
279 .RE
280 .PP
281 \fB\-ESTALE\fR
282 .RS 4
283 The event loop is already terminated\&.
284 .sp
285 Added in version 254\&.
286 .RE
287 .PP
288 \fB\-ECHILD\fR
289 .RS 4
290 The event loop has been created in a different process, library or module instance\&.
291 .sp
292 Added in version 254\&.
293 .RE
294 .PP
295 \fB\-EDOM\fR
296 .RS 4
297 The passed event source is not a signal event source\&.
298 .sp
299 Added in version 254\&.
300 .RE
301 .SH "NOTES"
302 .PP
303 Functions described here are available as a shared library, which can be compiled against and linked to with the
304 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
305 file\&.
306 .PP
307 The code described here uses
308 \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
309 \fBsetenv\fR(3)
310 from a parallel thread\&. It is recommended to only do calls to
311 \fBsetenv()\fR
312 from an early phase of the program when no other threads have been started\&.
313 .SH "HISTORY"
314 .PP
315 \fBsd_event_add_memory_pressure()\fR,
316 \fBsd_event_source_set_memory_pressure_type()\fR,
317 \fBsd_event_source_set_memory_pressure_period()\fR, and
318 \fBsd_event_trim_memory()\fR
319 were added in version 254\&.
320 .SH "SEE ALSO"
321 .PP
322 \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)
323 .SH "NOTES"
324 .IP " 1." 4
325 Pressure Stall Information (PSI)
326 .RS 4
327 \%https://docs.kernel.org/accounting/psi.html
328 .RE
329 .IP " 2." 4
330 Memory Pressure Handling in systemd
331 .RS 4
332 \%https://systemd.io/MEMORY_PRESSURE
333 .RE