SD_EVENT_..._PRESSURE(3)

💖 SD_EVENT_..._PRESSURE 💖

okay bestie, gather round, because this one is 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, and sd_event_source_set_io_pressure_period — section 3 of the systemd manual, and it's literally the whole "how do I get notified when my system is stressed" saga. 🫶

---

✨ 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 — these are the ones that add and configure an event source for memory, CPU, or IO pressure notifications. yes, all three. the whole pressure family. 💅

---

🌸 SYNOPSIS 🌸

#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_t handler,
                                 void *userdata);

int sd_event_source_set_memory_pressure_type(sd_event_source *source,
                                             const char *type);

int sd_event_source_set_memory_pressure_period(sd_event_source *source,
                                               uint64_t threshold_usec,
                                               uint64_t window_usec);

int sd_event_add_cpu_pressure(sd_event *event,
                              sd_event_source **ret_source,
                              sd_event_handler_t handler,
                              void *userdata);

int sd_event_source_set_cpu_pressure_type(sd_event_source *source,
                                          const char *type);

int sd_event_source_set_cpu_pressure_period(sd_event_source *source,
                                            uint64_t threshold_usec,
                                            uint64_t window_usec);

int sd_event_add_io_pressure(sd_event *event,
                             sd_event_source **ret_source,
                             sd_event_handler_t handler,
                             void *userdata);

int sd_event_source_set_io_pressure_type(sd_event_source *source,
                                         const char *type);

int sd_event_source_set_io_pressure_period(sd_event_source *source,
                                           uint64_t threshold_usec,
                                           uint64_t window_usec);

int sd_event_trim_memory(void);

---

🦋 DESCRIPTION 🦋

okay so here's the vibe. sd_event_add_memory_pressure() adds a brand new event source that fires whenever memory pressure is seen. and like, same energy, sd_event_add_cpu_pressure() and sd_event_add_io_pressure() add event sources that fire whenever CPU or IO pressure is seen, respectively. the whole thing is built around the Linux kernel's Pressure Stall Information (PSI)[1] logic. no cap, that's the actual mechanism. 👑

These functions expect an event loop object as first parameter, and they hand you back the allocated event source object in the second parameter if it works out. the handler parameter is a function to call when pressure is seen, or NULL. the handler gets passed the userdata pointer, which the caller can pick however they want, no judgement. the handler may return negative to signal an error (details below), and literally any other return value just gets ignored. if handler is NULL, a default handler is used instead:

• 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. like, it does nothing. 💀

so yeah, it is recommended to pass a custom handler for CPU and IO pressure if you actually want to take meaningful action when pressure is detected. the default one is giving "I showed up but I'm not doing anything."

To destroy an event source object use sd_event_source_unref(3), but note the fine print: the event source is only removed from the event loop when all references to the event source are dropped. so if you want to make absolutely 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. two different things, bestie. don't mix them up. 💅

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 that case the event source is considered "floating", and it will be destroyed implicitly when the event loop itself is destroyed. it just floats away, like a little butterfly. 🦋

---

🌈 the memory pressure firing logic 🌈

The memory pressure 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) for POLLPRI (in case it is a regular file) or POLLIN events (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.

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. that's just how it is, don't fight it.

The IO pressure event source follows the same logic too, 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.

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. manager first, then local, then global. that's the priority order, periodt.

---

🎀 what well-behaving services should do 🎀

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 as malloc_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). yes, literally just leave. it's allowed.

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. you're doing the system a solid. 🤝

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. the past pain is the whole point, bestie. 🫠

---

💜 fine-tuning the pressure parameters 💜

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, and the latter takes threshold and period times in microseconds as parameters. for details about these three parameters see the PSI documentation. 📖

⚠️ Careful, bestie: 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). so if you're getting failures here, that's why.

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

---

⭐ sd_event_trim_memory ⭐

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). so you're never locked out of the default behaviour — you can just call it yourself whenever you feel like it.

This function will log a structured log message at LOG_DEBUG level (with message ID f9b0be465ad540d0850ad32172d57c21) about the memory pressure operation. yes, that's the exact ID. screenshot it, it's iconic. 📸

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

---

💖 RETURN VALUE 💖

okay so bestie, here's the tea on what these functions hand back to you:

On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. that's it, that's the whole vibe.

---

😭 Errors 😭

when things go sideways, the errors you might get back are giving:

• -ENOMEM — not enough memory to allocate an object. the RAM said "no <3"

Added in version 254.

• -EINVAL — an invalid argument has been passed. you handed it something it cannot work with, bestie.

Added in version 254.

• -EHOSTDOWN — the $MEMORY_PRESSURE_WATCH, $CPU_PRESSURE_WATCH, or $IO_PRESSURE_WATCH variable has been set to the literal string /dev/null, in order to explicitly disable pressure handling. so yeah, you literally told it to stop watching and it's like "okay periodt, disabled" 🚫

Added in version 254.

• -EBADMSG — the $MEMORY_PRESSURE_WATCH, $CPU_PRESSURE_WATCH, or $IO_PRESSURE_WATCH variable has been set to an invalid string, for example a relative rather than an absolute path. it's giving "wrong address, no cap" 📭

Added in version 254.

• -ENOTTY — the $MEMORY_PRESSURE_WATCH, $CPU_PRESSURE_WATCH, or $IO_PRESSURE_WATCH variable points to a regular file outside of the procfs or cgroupfs file systems. like, bestie, that's not where pressure info lives 💀

Added in version 254.

• -EOPNOTSUPP — no configuration via $MEMORY_PRESSURE_WATCH, $CPU_PRESSURE_WATCH, or $IO_PRESSURE_WATCH has been specified, and the local kernel does not support the PSI interface. your kernel is lowkey not built different enough for this 😔

Added in version 254.

• -EBUSY — this one is returned by sd_event_source_set_memory_pressure_type(), sd_event_source_set_memory_pressure_period(), sd_event_source_set_cpu_pressure_type(), sd_event_source_set_cpu_pressure_period(), sd_event_source_set_io_pressure_type(), and sd_event_source_set_io_pressure_period() if you invoke them on event sources at a time later than immediately after allocating them. timing is everything, gorgeous. do it early or don't do it at all ✋

Added in version 254.

• -ESTALE — the event loop is already terminated. it's over, it has left the chat 🪦

Added in version 254.

• -ECHILD — the event loop has been created in a different process, library or module instance. not your kid, not your problem 👶

Added in version 254.

• -EDOM — the passed event source is not a signal event source. wrong type of source, wrong type of energy 🚫

Added in version 254.

---

🎀 NOTES 🎀

Functions described here are available as a shared library, which can be compiled against and linked to with the libsystemd pkg-config(1) file. yes, link it, she's ready 💅

All functions listed here are thread-agnostic and only a single thread may operate on a given object at any given time. Different threads may access the same object at different times. Multiple independent objects may be used from different threads in parallel. so like… share the object, but one at a time bestie, we're not chaos gremlins ✨

The code described here uses getenv(3), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not call setenv(3) from a parallel thread. It is recommended to only do calls to setenv() from an early phase of the program when no other threads have been started.

⚠️ okay this one actually matters: getenv(3) is not multi-thread-safe, so do not call setenv(3) from a parallel thread. set your env up early, before any other threads spawn. future you says thank you 🫶

---

👑 HISTORY 👑

sd_event_add_memory_pressure(), sd_event_source_set_memory_pressure_type(), sd_event_source_set_memory_pressure_period(), and sd_event_trim_memory() were added in version 254. the OGs, the originals, the icons ⭐

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(), and sd_event_source_set_io_pressure_period() were added in version 261. the newer girlies, also slaying 🌸

---

🌈 SEE ALSO 🌈

• 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)

go read those too, iykyk 📚

---

🦋 NOTES (the footnote kind) 🦋

1. Pressure Stall Information (PSI) — https://docs.kernel.org/accounting/psi.html
2. Resource Pressure Handling in systemd — https://systemd.io/PRESSURE

---

and that's a wrap on the whole page, bestie!! 🎀 this gorgeous thing came from systemd 262.1 and the manpage date stamps itself as SD_EVENT_..._PRESSURE(3). go forth, watch your pressure, and slay responsibly 💅✨🦋