sd_event_add_memory_pressure(3)

.SH "NAME" 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

.SH "SYNOPSIS"

#include <systemd/sd-event.h>

typedef struct sd_event_source sd_event_source;

.HP 792u int sd_event_add_memory_pressure(sd_event *event, sd_event_source **ret_source, sd_event_handler_t handler, void *userdata);

.HP 1080u int sd_event_source_set_memory_pressure_type(sd_event_source *source, const char *type);

.HP 1128u int sd_event_source_set_memory_pressure_period(sd_event_source *source, uint64_t threshold_usec, uint64_t window_usec);

.HP 720u int sd_event_add_cpu_pressure(sd_event *event, sd_event_source **ret_source, sd_event_handler_t handler, void *userdata);

.HP 1008u int sd_event_source_set_cpu_pressure_type(sd_event_source *source, const char *type);

.HP 1056u int sd_event_source_set_cpu_pressure_period(sd_event_source *source, uint64_t threshold_usec, uint64_t window_usec);

.HP 696u int sd_event_add_io_pressure(sd_event *event, sd_event_source **ret_source, sd_event_handler_t handler, void *userdata);

.HP 984u int sd_event_source_set_io_pressure_type(sd_event_source *source, const char *type);

.HP 1032u int sd_event_source_set_io_pressure_period(sd_event_source *source, uint64_t threshold_usec, uint64_t window_usec);

.HP 600u int sd_event_trim_memory(void);

.SH "DESCRIPTION"

.PP sd_event_add_memory_pressure() adds a new event source that is triggered whenever memory pressure is seen. Similarly, sd_event_add_cpu_pressure() and sd_event_add_io_pressure() add new event sources that are triggered whenever CPU or IO pressure is seen, respectively. This functionality is built around the Linux kernel's Pressure Stall Information (PSI)[1] logic.

.PP These functions expect an event loop object as first parameter, and return the allocated event source object in the second parameter, on success. The handler parameter is a function to call when pressure is seen, or NULL. The handler function will be passed the userdata 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 handler is NULL, a default handler is used. For sd_event_add_memory_pressure(), the default handler compacts allocation caches maintained by libsystemd as well as glibc (via malloc_trim(3)). For sd_event_add_cpu_pressure() and sd_event_add_io_pressure(), 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.

.PP To destroy an event source object use sd_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 using sd_event_source_set_enabled(3) with SD_EVENT_OFF.

.PP If the second parameter of sd_event_add_memory_pressure(), sd_event_add_cpu_pressure(), or sd_event_add_io_pressure() is NULL 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.

.PP The memory pressure event source will fire according to the following logic:

.PP The CPU pressure event source follows the same logic, but uses the $CPU_PRESSURE_WATCH/$CPU_PRESSURE_WRITE environment variables, the cpu.pressure cgroup file, and the system-wide PSI interface file /proc/pressure/cpu instead. Note that /proc/pressure/cpu only provides the some line, not the full line, so only some is valid when watching at the system level.

.PP The IO pressure event source follows the same logic, but uses the $IO_PRESSURE_WATCH/$IO_PRESSURE_WRITE environment variables, the io.pressure cgroup file, and the system-wide PSI interface file /proc/pressure/io instead.

.PP 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.

.PP 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:

.PP 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.

.PP 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.

.PP The sd_event_source_set_memory_pressure_type() and sd_event_source_set_memory_pressure_period() functions can be used to fine-tune the PSI parameters for memory 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).

.PP Similarly, sd_event_source_set_cpu_pressure_type() and sd_event_source_set_cpu_pressure_period() can be used to fine-tune the PSI parameters for CPU pressure notifications, and sd_event_source_set_io_pressure_type() and sd_event_source_set_io_pressure_period() 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 some or 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 $*_PRESSURE_WATCH/$*_PRESSURE_WRITE environment variables.

.PP The sd_event_trim_memory() function releases various internal allocation caches maintained by libsystemd and then invokes glibc's malloc_trim(3). This makes the operation executed when the handler function parameter of sd_event_add_memory_pressure is passed as NULL directly accessible for invocation at any time (see above). This function will log a structured log message at LOG_DEBUG level (with message ID f9b0be465ad540d0850ad32172d57c21) about the memory pressure operation.

.PP For further details see Resource Pressure Handling in systemd[2].

.SH "RETURN VALUE"

.PP On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code.

.SS "Errors"

.PP Returned errors may indicate the following problems:

.PP -ENOMEM