HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |SYNOPSIS |DESCRIPTION |RETURN VALUE |NOTES |HISTORY |SEE ALSO |NOTES |COLOPHON | |
SD_EVENT...PRESSURE(3) sd_event_add_memory_pressureSD_EVENT...PRESSURE(3)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
#include <systemd/sd-event.h>typedef struct sd_event_source sd_event_source;int sd_event_add_memory_pressure(sd_event *event,sd_event_source **ret_source,sd_event_handler_thandler,void *userdata);intsd_event_source_set_memory_pressure_type(sd_event_source *source,const char *type);intsd_event_source_set_memory_pressure_period(sd_event_source *source,uint64_tthreshold_usec,uint64_twindow_usec);int sd_event_trim_memory(void);
sd_event_add_memory_pressure()adds a new event source that is triggered whenever memory pressure is seen. This functionality is built around the Linux kernel'sPressure Stall Information(PSI)[1] logic. Expects an event loop object as first parameter, and returns the allocated event source object in the second parameter, on success. Thehandler parameter is a function to call when memory pressure is seen, orNULL. The handler function will be passed theuserdata 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. Ifhandler isNULL, a default handler that compacts allocation caches maintained by libsystemd as well as glibc (viamalloc_trim(3)) will be used. To destroy an event source object usesd_event_source_unref(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 usingsd_event_source_set_enabled(3) withSD_EVENT_OFF. If the second parameter ofsd_event_add_memory_pressure()isNULL 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. The event source will fire according to the following logic: 1. If the$MEMORY_PRESSURE_WATCH/$MEMORY_PRESSURE_WRITE environment variables are set at the time the event source is established, it will watch the file, FIFO or AF_UNIX socket specified via$MEMORY_PRESSURE_WATCH (which must contain an absolute path name) forPOLLPRI(in case it is a regular file) orPOLLINevents (otherwise). After opening the inode, it will write the (decoded) Base64 data provided via$MEMORY_PRESSURE_WRITE into it before it starts polling on it (the variable may be unset in which case this is skipped). Typically, if used,$MEMORY_PRESSURE_WATCH will contain a path such as /proc/pressure/memory or a path to a specific memory.pressure file in the control group file system (cgroupfs). 2. If these environment variables are not set, the local PSI interface file memory.pressure of the control group the invoking process is running in is used. 3. If that file does not exist, the system-wide PSI interface file /proc/pressure/memory is watched instead. 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. 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: • Release allocation caches such asmalloc_trim()or similar, both implemented in the libraries consumed by the program and in private allocation caches of the program itself. • Release any other form of in-memory caches that can easily be recovered if needed (e.g. browser caches). • Terminate idle worker threads or processes, or similar. • Even exit entirely from the program if it is idle and can be automatically started when needed (for example via socket or bus activation). 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. 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-aquire any released resources is acceptable: it is usually more important to think of the latencies that already happened than those coming up in future. Thesd_event_source_set_memory_pressure_type()andsd_event_source_set_memory_pressure_period()functions can be used to fine-tune the PSI parameters for pressure notifications. The former takes either "some", "full" 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$MEMORY_PRESSURE_WATCH/$MEMORY_PRESSURE_WRITE environment variables (or in other words: configuration supplied by a service manager wins over internal settings). Thesd_event_trim_memory()function releases various internal allocation caches maintained by libsystemd and then invokes glibc'smalloc_trim(3). This makes the operation executed when the handler function parameter ofsd_event_add_memory_pressureis passed asNULLdirectly accessible for invocation at any time (see above). This function will log a structured log message atLOG_DEBUGlevel (with message ID f9b0be465ad540d0850ad32172d57c21) about the memory pressure operation. For further details seeMemory Pressure Handling in systemd[2].
On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code.Errors Returned errors may indicate the following problems:-ENOMEM Not enough memory to allocate an object. Added in version 254.-EINVAL An invalid argument has been passed. Added in version 254.-EHOSTDOWN The$MEMORY_PRESSURE_WATCH variable has been set to the literal string /dev/null, in order to explicitly disable memory pressure handling. Added in version 254.-EBADMSG The$MEMORY_PRESSURE_WATCH variable has been set to an invalid string, for example a relative rather than an absolute path. Added in version 254.-ENOTTY The$MEMORY_PRESSURE_WATCH variable points to a regular file outside of the procfs or cgroupfs file systems. Added in version 254.-EOPNOTSUPP No configuration via$MEMORY_PRESSURE_WATCH has been specified and the local kernel does not support the PSI interface. Added in version 254.-EBUSY This is returned bysd_event_source_set_memory_pressure_type() andsd_event_source_set_memory_pressure_period()if invoked on event sources at a time later than immediately after allocating them. Added in version 254.-ESTALE The event loop is already terminated. Added in version 254.-ECHILD The event loop has been created in a different process, library or module instance. Added in version 254.-EDOM The passed event source is not a signal event source. Added in version 254.
Functions described here are available as a shared library, which can be compiled against and linked to with thelibsystemd pkg-config(1) file. The code described here usesgetenv(3), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not callsetenv(3) from a parallel thread. It is recommended to only do calls tosetenv()from an early phase of the program when no other threads have been started.
sd_event_add_memory_pressure(),sd_event_source_set_memory_pressure_type(),sd_event_source_set_memory_pressure_period(), andsd_event_trim_memory()were added in version 254.
systemd(1),sd-event(3),sd_event_new(3),sd_event_add_io(3),sd_event_add_time(3),sd_event_add_child(3),sd_event_add_inotify(3),sd_event_add_defer(3),sd_event_source_set_enabled(3),sd_event_source_set_description(3),sd_event_source_set_userdata(3),sd_event_source_set_floating(3)
1. Pressure Stall Information (PSI)https://docs.kernel.org/accounting/psi.html 2. Memory Pressure Handling in systemdhttps://systemd.io/MEMORY_PRESSURE
This page is part of thesystemd (systemd system and service manager) project. Information about the project can be found at ⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have a bug report for this manual page, see ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩. This page was obtained from the project's upstream Git repository ⟨https://github.com/systemd/systemd.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-08-11.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgsystemd 258~rc2SD_EVENT...PRESSURE(3)Pages that refer to this page:sd-event(3), systemd.resource-control(5), systemd.directives(7), systemd.index(7)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |