Product SiteDocumentation Site

3.7. memory

The memory subsystem generates automatic reports on memory resources used by the tasks in a cgroup, and sets limits on memory use by those tasks:
memory.stat
reports a wide range of memory statistics, as described in the following table:
Table 3.1. Values reported by memory.stat
Statistic Description
cache page cache, including tmpfs (shmem), in bytes
rss anonymous and swap cache, not including tmpfs (shmem), in bytes
mapped_file size of memory-mapped mapped files, including tmpfs (shmem), in bytes
pgpgin number of pages paged into memory
pgpgout number of pages paged out of memory
swap swap usage, in bytes
active_anon anonymous and swap cache on active least-recently-used (LRU) list, including tmpfs (shmem), in bytes
inactive_anon anonymous and swap cache on inactive LRU list, including tmpfs (shmem), in bytes
active_file file-backed memory on active LRU list, in bytes
inactive_file file-backed memory on inactive LRU list, in bytes
unevictable memory that cannot be reclaimed, in bytes
hierarchical_memory_limit memory limit for the hierarchy that contains the memory cgroup, in bytes
hierarchical_memsw_limit memory plus swap limit for the hierarchy that contains the memory cgroup, in bytes

Additionally, each of these files other than hierarchical_memory_limit and hierarchical_memsw_limit has a counterpart prefixed total_ that reports not only on the cgroup, but on all its children as well. For example, swap reports the swap usage by a cgroup and total_swap reports the total swap usage by the cgroup and all its child groups.
When you interpret the values reported by memory.stat, note how the various statistics inter-relate:
  • active_anon + inactive_anon = anonymous memory + file cache for tmpfs + swap cache
    Therefore, active_anon + inactive_anonrss, because rss does not include tmpfs.
  • active_file + inactive_file = cache - size of tmpfs
memory.usage_in_bytes
reports the total current memory usage by processes in the cgroup (in bytes).
memory.memsw.usage_in_bytes
reports the sum of current memory usage plus swap space used by processes in the cgroup (in bytes).
memory.max_usage_in_bytes
reports the maximum memory used by processes in the cgroup (in bytes).
memory.memsw.max_usage_in_bytes
reports the maximum amount of memory and swap space used by processes in the cgroup (in bytes).
memory.limit_in_bytes
sets the maximum amount of user memory (including file cache). If no units are specified, the value is interpreted as bytes. However, it is possible to use suffixes to represent larger units — k or K for kilobytes, m or M for Megabytes, and g or G for Gigabytes.
You cannot use memory.limit_in_bytes to limit the root cgroup; you can only apply values to groups lower in the hierarchy.
Write -1 to memory.limit_in_bytes to remove any existing limits.
memory.memsw.limit_in_bytes
sets the maximum amount for the sum of memory and swap usage. If no units are specified, the value is interpreted as bytes. However, it is possible to use suffixes to represent larger units — k or K for kilobytes, m or M for Megabytes, and g or G for Gigabytes.
You cannot use memory.memsw.limit_in_bytes to limit the root cgroup; you can only apply values to groups lower in the hierarchy.
Write -1 to memory.memsw.limit_in_bytes to remove any existing limits.

Setting the memory.memsw.limit_in_bytes and memory.limit_in_bytes parameters

It is important to set the memory.limit_in_bytes parameter before setting the memory.memsw.limit_in_bytes parameter; attempting to do so in the reverse order results in an error. This is because memory.memsw.limit_in_bytes becomes available only after all memory limitations (previously set in memory.limit_in_bytes) are exhausted.
Consider the following example: setting memory.limit_in_bytes = 2G and memory.memsw.limit_in_bytes = 4G for a certain cgroup will allow processes in that cgroup to allocate 2 GB of memory and, once exhausted, allocate another 2 GB of swap only; the memory.memsw.limit_in_bytes parameter represents a sum of memory and swap. Processes in a cgroup that does not have the memory.memsw.limit_in_bytes parameter set can potentially use up all the available swap (after exhausting the set memory limitation) and trigger an Out Of Memory situation caused by the lack of available swap.
The order in which the memory.limit_in_bytes and memory.memsw.limit_in_bytes parameters are set in the /etc/cgconfig.conf file is important as well. The following is a correct example of such a configuration:
memory {
    memory.limit_in_bytes = 1G;
    memory.memsw.limit_in_bytes = 1G;
}
memory.failcnt
reports the number of times that the memory limit has reached the value set in memory.limit_in_bytes.
memory.memsw.failcnt
reports the number of times that the memory plus swap space limit has reached the value set in memory.memsw.limit_in_bytes.
memory.force_empty
when set to 0, empties memory of all pages used by tasks in this cgroup. This interface can only be used when the cgroup has no tasks. If memory cannot be freed, it is moved to a parent cgroup if possible. Use the memory.force_empty parameter before removing a cgroup to avoid moving out-of-use page caches to its parent cgroup.
memory.swappiness
sets the tendency of the kernel to swap out process memory used by tasks in this cgroup instead of reclaiming pages from the page cache. This is the same tendency, calculated the same way, as set in /proc/sys/vm/swappiness for the system as a whole. The default value is 60. Values lower than 60 decrease the kernel's tendency to swap out process memory, values greater than 60 increase the kernel's tendency to swap out process memory, and values greater than 100 permit the kernel to swap out pages that are part of the address space of the processes in this cgroup.
Note that a value of 0 does not prevent process memory being swapped out; swap out might still happen when there is a shortage of system memory because the global virtual memory management logic does not read the cgroup value. To lock pages completely, use mlock() instead of cgroups.
You cannot change the swappiness of the following groups:
  • the root cgroup, which uses the swappiness set in /proc/sys/vm/swappiness.
  • a cgroup that has child groups below it.
memory.use_hierarchy
contains a flag (0 or 1) that specifies whether memory usage should be accounted for throughout a hierarchy of cgroups. If enabled (1), the memory subsystem reclaims memory from the children of and process that exceeds its memory limit. By default (0), the subsystem does not reclaim memory from a task's children.