sd_event_trim_memory(3)

1SD_EVENT_ADD_MEMORY_PRESSUsRdE_(e3v)ent_add_memory_preSsDs_uErVeENT_ADD_MEMORY_PRESSURE(3)
2
3
4

NAME

6       sd_event_add_memory_pressure, sd_event_source_set_memory_pressure_type,
7       sd_event_source_set_memory_pressure_period, sd_event_trim_memory - Add
8       and configure an event source run as result of memory pressure
9

SYNOPSIS

11       #include <systemd/sd-event.h>
12
13       typedef struct sd_event_source sd_event_source;
14
15       int sd_event_add_memory_pressure(sd_event *event,
16                                        sd_event_source **ret_source,
17                                        sd_event_handler_t handler,
18                                        void *userdata);
19
20       int sd_event_source_set_memory_pressure_type(sd_event_source *source,
21                                                    const char *type);
22
23       int sd_event_source_set_memory_pressure_period(sd_event_source *source,
24                                                      uint64_t threshold_usec,
25                                                      uint64_t window_usec);
26
27       int sd_event_trim_memory(void);
28

DESCRIPTION

30       sd_event_add_memory_pressure() adds a new event source that is
31       triggered whenever memory pressure is seen. This functionality is built
32       around the Linux kernel's Pressure Stall Information (PSI)[1] logic.
33
34       Expects an event loop object as first parameter, and returns the
35       allocated event source object in the second parameter, on success. The
36       handler parameter is a function to call when memory pressure is seen,
37       or NULL. The handler function will be passed the userdata pointer,
38       which may be chosen freely by the caller. The handler may return
39       negative to signal an error (see below), other return values are
40       ignored. If handler is NULL, a default handler that compacts allocation
41       caches maintained by libsystemd as well as glibc (via malloc_trim(3))
42       will be used.
43
44       To destroy an event source object use sd_event_source_unref(3), but
45       note that the event source is only removed from the event loop when all
46       references to the event source are dropped. To make sure an event
47       source does not fire anymore, even if it is still referenced, disable
48       the event source using sd_event_source_set_enabled(3) with
49       SD_EVENT_OFF.
50
51       If the second parameter of sd_event_add_memory_pressure() is NULL no
52       reference to the event source object is returned. In this case the
53       event source is considered "floating", and will be destroyed implicitly
54       when the event loop itself is destroyed.
55
56       The event source will fire according to the following logic:
57
58        1. If the $MEMORY_PRESSURE_WATCH/$MEMORY_PRESSURE_WRITE environment
59           variables are set at the time the event source is established, it
60           will watch the file, FIFO or AF_UNIX socket specified via
61           $MEMORY_PRESSURE_WATCH (which must contain an absolute path name)
62           for POLLPRI (in case it is a regular file) or POLLIN events
63           (otherwise). After opening the inode, it will write the (decoded)
64           Base64 data provided via $MEMORY_PRESSURE_WRITE into it before it
65           starts polling on it (the variable may be unset in which case this
66           is skipped). Typically, if used, $MEMORY_PRESSURE_WATCH will
67           contain a path such as /proc/pressure/memory or a path to a
68           specific memory.pressure file in the control group file system
69           (cgroupfs).
70
71        2. If these environment variables are not set, the local PSI interface
72           file memory.pressure of the control group the invoking process is
73           running in is used.
74
75        3. If that file does not exist, the system-wide PSI interface file
76           /proc/pressure/memory is watched instead.
77
78       Or in other words: preferably any explicit configuration passed in by
79       an invoking service manager (or similar) is used as notification
80       source, before falling back to local notifications of the service, and
81       finally to global notifications of the system.
82
83       Well-behaving services and applications are recommended to react to
84       memory pressure events by executing one or more of the following
85       operations, in order to ensure optimal behaviour even on loaded and
86       resource-constrained systems:
87
88       •   Release allocation caches such as malloc_trim() or similar, both
89           implemented in the libraries consumed by the program and in private
90           allocation caches of the program itself.
91
92       •   Release any other form of in-memory caches that can easily be
93           recovered if needed (e.g. browser caches).
94
95       •   Terminate idle worker threads or processes, or similar.
96
97       •   Even exit entirely from the program if it is idle and can be
98           automatically started when needed (for example via socket or bus
99           activation).
100
101       Any of the suggested operations should help easing memory pressure
102       situations and allowing the system to make progress by reclaiming the
103       memory for other purposes.
104
105       This event source typically fires on memory pressure stalls, i.e. when
106       operational latency above a configured threshold already has been seen.
107       This should be taken into consideration when discussing whether later
108       latency to re-aquire any released resources is acceptable: it's usually
109       more important to think of the latencies that already happened than
110       those coming up in future.
111
112       The sd_event_source_set_memory_pressure_type() and
113       sd_event_source_set_memory_pressure_period() functions can be used to
114       fine-tune the PSI parameters for pressure notifications. The former
115       takes either "some", "full" as second parameter, the latter takes
116       threshold and period times in microseconds as parameters. For details
117       about these three parameters see the PSI documentation. Note that these
118       two calls must be invoked immediately after allocating the event
119       source, as they must be configured before polling begins. Also note
120       that these calls will fail if memory pressure parameterization has been
121       passed in via the $MEMORY_PRESSURE_WATCH/$MEMORY_PRESSURE_WRITE
122       environment variables (or in other words: configuration supplied by a
123       service manager wins over internal settings).
124
125       The sd_event_trim_memory() function releases various internal
126       allocation caches maintained by libsystemd and then invokes glibc's
127       malloc_trim(3). This makes the operation executed when the handler
128       function parameter of sd_event_add_memory_pressure is passed as NULL
129       directly accessible for invocation at any time (see above). This
130       function will log a structured log message at LOG_DEBUG level (with
131       message ID f9b0be465ad540d0850ad32172d57c21) about the memory pressure
132       operation.
133
134       For further details see Memory Pressure Handling in systemd[2].
135

RETURN VALUE

137       On success, these functions return 0 or a positive integer. On failure,
138       they return a negative errno-style error code.
139
140   Errors
141       Returned errors may indicate the following problems:
142
143       -ENOMEM
144           Not enough memory to allocate an object.
145
146       -EINVAL
147           An invalid argument has been passed.
148
149       -EHOSTDOWN
150           The $MEMORY_PRESSURE_WATCH variable has been set to the literal
151           string /dev/null, in order to explicitly disable memory pressure
152           handling.
153
154       -EBADMSG
155           The $MEMORY_PRESSURE_WATCH variable has been set to an invalid
156           string, for example a relative rather than an absolute path.
157
158       -ENOTTY
159           The $MEMORY_PRESSURE_WATCH variable points to a regular file
160           outside of the procfs or cgroupfs file systems.
161
162       -EOPNOTSUPP
163           No configuration via $MEMORY_PRESSURE_WATCH has been specified and
164           the local kernel does not support the PSI interface.
165
166       -EBUSY
167           This is returned by sd_event_source_set_memory_pressure_type() and
168           sd_event_source_set_memory_pressure_period() if invoked on event
169           sources at a time later than immediately after allocating them.
170
171       -ESTALE
172           The event loop is already terminated.
173
174       -ECHILD
175           The event loop has been created in a different process, library or
176           module instance.
177
178       -EDOM
179           The passed event source is not a signal event source.
180

NOTES

182       Functions described here are available as a shared library, which can
183       be compiled against and linked to with the libsystemd pkg-config(1)
184       file.
185
186       The code described here uses getenv(3), which is declared to be not
187       multi-thread-safe. This means that the code calling the functions
188       described here must not call setenv(3) from a parallel thread. It is
189       recommended to only do calls to setenv() from an early phase of the
190       program when no other threads have been started.
191

NOTES

200        1. Pressure Stall Information (PSI)
201           https://docs.kernel.org/accounting/psi.html
202
203        2. Memory Pressure Handling in systemd
204           https://systemd.io/MEMORY_PRESSURE
205
206
207
208systemd 254                                    SD_EVENT_ADD_MEMORY_PRESSURE(3)

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

SEE ALSO

NOTES