2 * Copyright © 2012-2013 Canonical Ltd.
4 * This program is free software: you can redistribute it and/or modify it
5 * under the terms of the GNU Lesser General Public License version 3,
6 * as published by the Free Software Foundation.
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU Lesser General Public License for more details.
13 * You should have received a copy of the GNU Lesser General Public License
14 * along with this program. If not, see <http://www.gnu.org/licenses/>.
16 * Authored by: Thomas Voß <thomas.voss@canonical.com>
18 #ifndef CORE_POSIX_LINUX_PROC_PROCESS_OOM_SCORE_ADJ_H_
19 #define CORE_POSIX_LINUX_PROC_PROCESS_OOM_SCORE_ADJ_H_
21 #include <core/posix/visibility.h>
35 * This file can be used to adjust the badness heuristic used to select which
36 * process gets killed in out-of-memory conditions.
38 * The badness heuristic assigns a value to each candidate task ranging from 0
39 * (never kill) to 1000 (always kill) to determine which process is targeted.
40 * The units are roughly a proportion along that range of allowed memory the
41 * process may allocate from, based on an estimation of its current memory and
42 * swap use. For example, if a task is using all allowed memory, its badness
43 * score will be 1000. If it is using half of its allowed memory, its score
46 * There is an additional factor included in the badness score: root processes are
47 * given 3% extra memory over other tasks.
49 * The amount of "allowed" memory depends on the context in which the
50 * OOM-killer was called. If it is due to the memory assigned to the allocating
51 * task's cpuset being exhausted, the allowed memory represents the set of mems
52 * assigned to that cpuset (see cpuset(7)). If it is due to a mempolicy's node(s)
53 * being exhausted, the allowed memory represents the set of mempolicy nodes. If
54 * it is due to a memory limit (or swap limit) being reached, the allowed memory
55 * is that configured limit. Finally, if it is due to the entire system being out
56 * of memory, the allowed memory represents all allocatable resources.
58 * The value of oom_score_adj is added to the badness score before it is used
59 * to determine which task to kill. Acceptable values range from -1000
60 * (OOM_SCORE_ADJ_MIN) to +1000 (OOM_SCORE_ADJ_MAX). This allows user space to
61 * control the preference for OOM-killing, ranging from always preferring a
62 * certain task or completely disabling it from OOM- killing. The lowest possible
63 * value, -1000, is equivalent to disabling OOM-killing entirely for that task,
64 * since it will always report a badness score of 0.
66 * Consequently, it is very simple for user space to define the amount of
67 * memory to consider for each task. Setting a oom_score_adj value of +500, for
68 * example, is roughly equivalent to allowing the remainder of tasks sharing
69 * the same system, cpuset, mempolicy, or memory controller resources to use at
70 * least 50% more memory. A value of -500, on the other hand, would be roughly
71 * equivalent to discounting 50% of the task's allowed memory from being
72 * considered as scoring against the task.
74 * For backward compatibility with previous kernels, /proc/[pid]/oom_adj can
75 * still be used to tune the badness score. Its value is scaled linearly with
78 * Writing to /proc/[pid]/oom_score_adj or /proc/[pid]/oom_adj will change the
79 * other with its scaled value.
81 struct CORE_POSIX_DLL_PUBLIC OomScoreAdj
84 * @brief Returns the minimum valid value.
85 * @return The minimum valid value that the Oom Score Adj can be set to.
87 static int min_value();
90 * @brief Returns the maximum valid value.
91 * @return The maximum valid value that the Oom Score Adj can be set to.
93 static int max_value();
96 * @brief is_valid checks whether the contained value is within the predefined bounds.
97 * @return true iff min_value() <= value <= max_value().
99 inline bool is_valid() const
101 return (min_value() <= value) && (value <= max_value());
105 * @brief Current value.
111 * @brief Read the OomScoreAdj value for a process instance.
112 * @throw std::runtime_error in case of errors.
113 * @param [in] process The process to read the score for.
114 * @param [out] score_adj The destination to store the value in.
116 CORE_POSIX_DLL_PUBLIC const posix::Process& operator>>(const posix::Process& process, OomScoreAdj& score_adj);
119 * @brief Write the OomScoreAdj value for a process instance.
120 * @throw std::runtime_error in case of errors and std::logic_error if score_adj.is_valid() returns false.
121 * @param [in] process The process to write the score for.
122 * @param [in] score_adj The new value to store.
124 CORE_POSIX_DLL_PUBLIC const posix::Process& operator<<(const posix::Process& process,
125 const OomScoreAdj& score_adj);
131 #endif // CORE_POSIX_LINUX_PROC_PROCESS_OOM_SCORE_ADJ_H_