memsup(3)

💾 memsup(3) — the memory supervisor bestie 💖

okay so. this is the man page for memsup, a Memory Supervisor Process, straight outta the Erlang docs. it's a <pink>3</pink> page (library function, iykyk). buckle up, we're talking RAM. 🧠✨

---

🌸 NAME 🌸

memsup — A Memory Supervisor Process 🫶

---

✨ DESCRIPTION ✨

so memsup is a process whose whole job — its main character energy, honestly — is supervising the memory usage of the system and of individual processes. it lives inside the OS_Mon application (go peek at os_mon 💅). available for Unix and Windows, because inclusivity. 🌈

every so often it does a little memory check, period:

• if more than a certain amount of available system memory is allocated, as reported by the underlying operating system, the alarm {system_memory_high_watermark, []} gets set. 🚨 how the amount of available memory is determined depends on the underlying OS and may change as better values become available — so don't get too attached to the method, bestie.
• if any Erlang process Pid in the system has allocated more than a certain amount of total system memory, the alarm {process_memory_high_watermark, Pid} gets set. 😭 that one process said "i'll take everything."

alarms get reported to the SASL alarm handler, see alarm_handler. to set an alarm, alarm_handler:set_alarm(Alarm) is called where Alarm is either of the alarms specified above. periodt.

and bestie — the alarms are cleared automatically when the alarm cause is no longer valid. self-care. 💅

the function get_memory_data() can be used to retrieve the result of the latest periodic memory check.

there's also an interface to system dependent memory data, get_system_memory_data(). the result is highly dependent on the underlying operating system, and the interface is targeted primarily for systems without virtual memory. however, the output on other systems is still valid, although sparse. 🙈

a call to get_system_memory_data/0 is more costly than a call to get_memory_data/0 as data is collected synchronously when this function is called. so like… it's the expensive one. ⭐

the total system memory reported under UNIX is the number of physical pages of memory times the page size, and the available memory is the number of available physical pages times the page size. this is a reasonable measure as swapping should be avoided anyway, but the task of defining total memory and available memory is difficult because of virtual memory and swapping. it's giving it's complicated. 💀

🎀 Configuration 🎀

the following configuration parameters can be used to change the default values for time intervals and thresholds:

• memory_check_interval = int()>0 — the time interval, in minutes, for the periodic memory check. the default is one minute. ⏰
• system_memory_high_watermark = float() — the threshold, as percentage of system memory, for how much system memory can be allocated before the corresponding alarm is set. the default is 0.80 (80%). 🔥
• process_memory_high_watermark = float() — the threshold, as percentage of system memory, for how much system memory can be allocated by one Erlang process before the corresponding alarm is set. the default is 0.05 (5%). 👀
• memsup_helper_timeout = int()>0 — a timeout, in seconds, for how long the memsup process should wait for a result from a memory check. if the timeout expires, a warning message "OS_MON (memsup) timeout" is issued via error_logger and any pending, synchronous client calls will return a dummy value. normally, this situation should not occur. there have been cases on Linux, however, where the pseudo file from which system data is read is temporarily unavailable when the system is heavily loaded. the default is 30 seconds. ⌛
• memsup_system_only = bool() — specifies whether the memsup process should only check system memory usage (true) or not. the default is false, meaning that information regarding both system memory usage and Erlang process memory usage is collected. it is recommended to set this parameter to true on systems with many concurrent processes, as each process memory check makes a traversal of the entire list of processes. 🏃♀️💨

see config for information about how to change the value of configuration parameters.

🦋 See Also 🦋

alarm_handler, os_mon

---

👑 FUNCTIONS 👑

get_check_interval() -> Milliseconds :: timer:time().

returns the time interval, in milliseconds, for the periodic memory check. ⏱️

get_helper_timeout() -> Seconds :: integer().

returns the timeout value, in seconds, for memory checks.

get_memory_data() -> {Total, Allocated, Worst}

when
    Total :: integer(),
    Allocated :: integer(),
    Worst :: {Pid, PidAllocated} | undefined,
    Pid :: pid(),
    PidAllocated :: integer().

returns the result of the latest memory check, where Total is the total memory size and Allocated the allocated memory size, in bytes. 📏

Worst is the pid and number of allocated bytes of the largest Erlang process on the node. if memsup should not collect process data — that is, if the configuration parameter memsup_system_only was set to true — Worst is undefined.

the function is normally asynchronous in the sense that it does not invoke a memory check, but returns the latest available value. the one exception is if the function is called before a first memory check is finished, in which case it does not return a value until the memory check is finished. 😤 patience, bestie.

returns {0,0,{pid(),0}} or {0,0,undefined} if memsup is not available, or if all memory checks so far have timed out. 💀

get_os_wordsize() -> Wordsize

when Wordsize :: 32 | 64 | unsupported_os.

returns the wordsize of the current running operating system. 🖥️

get_procmem_high_watermark() -> integer().

returns the threshold, in percent, for process memory allocation.

get_sysmem_high_watermark() -> integer().

returns the threshold, in percent, for system memory allocation.

get_system_memory_data() -> MemDataList

when
    MemDataList :: [{Tag, Size}],
    Tag :: atom(),
    Size :: integer().

invokes a memory check and returns the resulting, system dependent, data as a list of tagged tuples, where Tag currently can be one of the following:

• total_memory — the total amount of memory available to the Erlang emulator, allocated and free. may or may not be equal to the amount of memory configured in the system. 🤷♀️
• available_memory — informs about the amount of memory that is available for increased usage if there is an increased memory need. this value is not based on a calculation of the other provided values and should give a better value of the amount of memory that actually is available than calculating a value based on the other values reported. this value is currently only present on newer Linux kernels. if this value is not available on Linux, you can use the sum of cached_memory, buffered_memory, and free_memory as an approximation. 🐧✨
• free_memory — the amount of free memory available to the Erlang emulator for allocation.
• system_total_memory — the amount of memory available to the whole operating system. this may well be equal to total_memory but not necessarily.
• buffered_memory — the amount of memory the system uses for temporary storing raw disk blocks.
• cached_memory — the amount of memory the system uses for cached files read from disk. on Linux, also memory marked as reclaimable in the kernel slab allocator will be added to this value.
• total_swap — the amount of total amount of memory the system has available for disk swap.
• free_swap — the amount of memory the system has available for disk swap.

NOTE: note that new tagged tuples may be introduced in the result at any time without prior notice. 🙈 no cap.

note that the order of the tuples in the resulting list is undefined and may change at any time. so don't you dare pattern match like it's a fixed order, bestie. 😭

all memory sizes are presented as number of bytes.

returns the empty list [] if memsup is not available, or if the memory check times out.

set_check_interval(Minutes :: non_neg_integer()) -> ok.

changes the time interval, given in minutes, for the periodic memory check.

the change will take effect after the next memory check and is non-persistent. that is, in case of a process restart, this value is forgotten and the default value will be used. see Configuration. 🫠

set_helper_timeout(Seconds :: non_neg_integer()) -> ok.

changes the timeout value, given in seconds, for memory checks.

the change will take effect for the next memory check and is non-persistent. that is, in the case of a process restart, this value is forgotten and the default value will be used. see Configuration above. 🫠

set_procmem_high_watermark(Float :: term()) -> ok.

changes the threshold, given as a float, for process memory allocation.

the change will take effect during the next periodic memory check and is non-persistent. that is, in case of a process restart, this value is forgotten and the default value will be used. see Configuration. 🫠

set_sysmem_high_watermark(Float :: term()) -> ok.

changes the threshold, given as a float, for system memory allocation.

the change will take effect during the next periodic memory check and is non-persistent. that is, in case of a process restart, this value is forgotten and the default value will be used. see Configuration above. 🫠

---

and that's the whole page, bestie!! 💖 brought to you by Ericsson AB, <pink>os_mon</pink> version <pink>2.12</pink>, and the memsup(3) manual page. go forth and monitor that memory, queen. 👑🦋💅