Apache Mesos
sorter.hpp
Go to the documentation of this file.
1 // Licensed to the Apache Software Foundation (ASF) under one
2 // or more contributor license agreements. See the NOTICE file
3 // distributed with this work for additional information
4 // regarding copyright ownership. The ASF licenses this file
5 // to you under the Apache License, Version 2.0 (the
6 // "License"); you may not use this file except in compliance
7 // with the License. You may obtain a copy of the License at
8 //
9 // http://www.apache.org/licenses/LICENSE-2.0
10 //
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
16 
17 #ifndef __MASTER_ALLOCATOR_MESOS_SORTER_SORTER_HPP__
18 #define __MASTER_ALLOCATOR_MESOS_SORTER_SORTER_HPP__
19 
20 #include <functional>
21 #include <string>
22 #include <utility>
23 #include <vector>
24 
25 #include <mesos/resources.hpp>
26 #include <mesos/type_utils.hpp>
27 
28 #include <process/pid.hpp>
29 
30 namespace mesos {
31 namespace internal {
32 namespace master {
33 namespace allocator {
34 
35 // Sorters implement the logic for determining the
36 // order in which users or frameworks should receive
37 // resource allocations.
38 //
39 // TODO(bmahler): Templatize this on Client, so that callers can
40 // don't need to do string conversion, e.g. FrameworkID, string role,
41 // etc.
42 class Sorter
43 {
44 public:
45  Sorter() = default;
46 
47  // Provides the allocator's execution context (via a UPID)
48  // and a name prefix in order to support metrics within the
49  // sorter implementation.
50  explicit Sorter(
51  const process::UPID& allocator,
52  const std::string& metricsPrefix) {}
53 
54  virtual ~Sorter() = default;
55 
56  // Initialize the sorter.
57  virtual void initialize(
58  const Option<std::set<std::string>>& fairnessExcludeResourceNames) = 0;
59 
60  // Adds a client to allocate resources to.
61  // A client may be a user or a framework.
62  // This function will not activate the client.
63  virtual void add(const std::string& client) = 0;
64 
65  // Removes a client.
66  virtual void remove(const std::string& client) = 0;
67 
68  // Readds a client to the sort after deactivate.
69  // It is a no-op if the client is already in the sort.
70  virtual void activate(const std::string& client) = 0;
71 
72  // Removes a client from the sort, so it won't get allocated to.
73  // It is a no-op if the client is already not in the sort.
74  virtual void deactivate(const std::string& client) = 0;
75 
76  // Updates the weight of a client path. This changes the sorter's
77  // behavior for all clients in the subtree identified by this path
78  // (both clients currently in the sorter and any clients that may be
79  // added later). If a client's weight is not explicitly set, the
80  // default weight of 1.0 is used. This interface does not support
81  // unsetting previously set weights; instead, the weight should be
82  // reset to the default value.
83  virtual void updateWeight(const std::string& path, double weight) = 0;
84 
85  // Specify that resources have been allocated to the given client.
86  virtual void allocated(
87  const std::string& client,
88  const SlaveID& slaveId,
89  const Resources& resources) = 0;
90 
91  // Updates a portion of the allocation for the client, in order to augment the
92  // resources with additional metadata (e.g., volumes), or remove certain
93  // resources. If the roles or scalar quantities are changed, the order of the
94  // clients should be updated accordingly.
95  virtual void update(
96  const std::string& client,
97  const SlaveID& slaveId,
98  const Resources& oldAllocation,
99  const Resources& newAllocation) = 0;
100 
101  // Specify that resources have been unallocated from the given client.
102  virtual void unallocated(
103  const std::string& client,
104  const SlaveID& slaveId,
105  const Resources& resources) = 0;
106 
107  // Returns the resources that have been allocated to this client.
109  const std::string& client) const = 0;
110 
111  // Returns the total scalar resource quantities that are allocated to
112  // a client, or all clients if a client is not provided.
114  const std::string& client) const = 0;
115  virtual const ResourceQuantities& allocationScalarQuantities() const = 0;
116 
117  // Returns the given slave's resources that have been allocated to
118  // this client.
119  virtual Resources allocation(
120  const std::string& client,
121  const SlaveID& slaveId) const = 0;
122 
123  // Add/remove total scalar resource quantities of an agent to/from the
124  // total pool of resources this Sorter should consider.
125  //
126  // NOTE: Updating resources of an agent in the Sorter is done by first calling
127  // `removeSlave()` and then `addSlave()` with new resource quantities.
128  //
129  // NOTE: Attempt to add the same agent twice or remove an agent not added
130  // to the Sorter may crash the program.
131  virtual void addSlave(
132  const SlaveID& slaveId,
133  const ResourceQuantities& scalarQuantities) = 0;
134 
135  virtual void removeSlave(const SlaveID& slaveId) = 0;
136 
137  // Returns all of the clients in the order that they should
138  // be allocated to, according to this Sorter's policy.
139  virtual std::vector<std::string> sort() = 0;
140 
141  // Returns true if this Sorter contains the specified client,
142  // which may be active or inactive.
143  virtual bool contains(const std::string& client) const = 0;
144 
145  // Returns the number of clients this Sorter contains,
146  // either active or inactive.
147  virtual size_t count() const = 0;
148 };
149 
150 
151 } // namespace allocator {
152 } // namespace master {
153 } // namespace internal {
154 } // namespace mesos {
155 
156 #endif // __MASTER_ALLOCATOR_MESOS_SORTER_SORTER_HPP__
Definition: path.hpp:29
virtual void removeSlave(const SlaveID &slaveId)=0
virtual void unallocated(const std::string &client, const SlaveID &slaveId, const Resources &resources)=0
Definition: option.hpp:29
Sorter(const process::UPID &allocator, const std::string &metricsPrefix)
Definition: sorter.hpp:50
Definition: master.hpp:27
Definition: resource_quantities.hpp:63
Definition: resources.hpp:83
virtual void initialize(const Option< std::set< std::string >> &fairnessExcludeResourceNames)=0
virtual const hashmap< SlaveID, Resources > & allocation(const std::string &client) const =0
virtual void update(const std::string &client, const SlaveID &slaveId, const Resources &oldAllocation, const Resources &newAllocation)=0
virtual void updateWeight(const std::string &path, double weight)=0
virtual const ResourceQuantities & allocationScalarQuantities() const =0
Definition: hashmap.hpp:38
An "untyped" PID, used to encapsulate the process ID for lower-layer abstractions (eg...
Definition: pid.hpp:39
Definition: agent.hpp:25
virtual bool contains(const std::string &client) const =0
Definition: attributes.hpp:24
virtual void add(const std::string &client)=0
virtual std::vector< std::string > sort()=0
virtual void addSlave(const SlaveID &slaveId, const ResourceQuantities &scalarQuantities)=0
virtual void activate(const std::string &client)=0
virtual void deactivate(const std::string &client)=0
virtual void allocated(const std::string &client, const SlaveID &slaveId, const Resources &resources)=0