# sd_event_add_memory_pressure

## NAME



           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
    


## 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_trim_memory(void);**
    


## DESCRIPTION



           **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's **Pressure 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.
           The _handler_ parameter is a function to call when memory 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 that
           compacts allocation caches maintained by libsystemd as well as
           glibc (via malloc_trim(3)) will be used.
    
           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**.
    
           If the second parameter of **sd_event_add_memory_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.
    
           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) 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.
    
           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 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).
    
           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.
    
           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 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).
    
           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.
    
           For further details see **Memory Pressure Handling in systemd******[2].


## RETURN VALUE



           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 by **sd_event_source_set_memory_pressure_type()**
               and **sd_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.
    


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


## NOTES



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


* * *