Apache Mesos
resources_utils.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 __RESOURCES_UTILS_HPP__
18 #define __RESOURCES_UTILS_HPP__
19 
20 #include <vector>
21 
22 #include <google/protobuf/repeated_field.h>
23 
24 #include <mesos/mesos.hpp>
25 #include <mesos/resources.hpp>
26 
27 #include <mesos/v1/mesos.hpp>
28 #include <mesos/v1/resources.hpp>
29 
30 #include <stout/error.hpp>
31 #include <stout/nothing.hpp>
32 #include <stout/option.hpp>
33 #include <stout/try.hpp>
34 
35 namespace mesos {
36 
37 // Tests if the given Resource needs to be checkpointed on the slave.
38 // NOTE: We assume the given resource is validated.
39 bool needCheckpointing(const Resource& resource);
40 
41 // Returns the total resources by applying the given checkpointed
42 // resources to the given resources. This function is useful when we
43 // want to calculate the total resources of a slave from the resources
44 // specified from the command line and the checkpointed resources.
45 // Returns error if the given resources are not compatible with the
46 // given checkpointed resources.
48  const Resources& resources,
49  const Resources& checkpointedResources);
50 
51 
52 // Returns the resource provider ID associated with the given
53 // operation. Returns None() if the operation is for agent default
54 // resources. We assume the given operation is validated. Therefore,
55 // the specified operation should not contain resources from more than
56 // one resource provider.
58  const Offer::Operation& operation);
59 
60 
61 // Returns the resource conversions from the given offer operation.
62 // This helper assumes that the given operation has already been
63 // validated.
65  const Offer::Operation& operation);
66 
67 
68 // Returns the resource conversions from the given offer operation.
69 // This helper assumes that the given operation has already been
70 // validated.
72  const v1::Offer::Operation& operation);
73 
74 
75 // Resource format options to be used with the `convertResourceFormat` function.
76 //
77 // The preconditions of the options are asymmetric, centered around the
78 // "post-reservation-refinement" format. This is mainly due to the fact that
79 // "post-reservation-refinement" format is our canonical representation.
80 // The transformations are generally applied to any of the 3 formats to be
81 // converted to the canonical format, then later converted back as necessary.
82 //
83 // See 'Resource Format' section in `mesos.proto` for more details.
85 {
86  // "post-reservation-refinement" -> "pre-reservation-refinement"
87  //
88  // The `Resource` objects must be in the "post-reservation-refinement" format,
89  // and must not have refined reservations.
90  //
91  // All resources end up with the `Resource.role` and `Resource.reservation`
92  // fields set, and the `Resource.reservations` field unset.
93  //
94  // We convert the resources to the "pre-reservation-refinement" format to
95  // checkpoint resources for example. This enables downgrading to an agent
96  // without a RESERVATION_REFINEMENT caapbility, since the resources will
97  // be checkpointed in a format that the downgraded agent can recover from.
99 
100  // "pre-reservation-refinement" -> "post-reservation-refinement"
101  // "post-reservation-refinement" -> "post-reservation-refinement"
102  // "endpoint" -> "post-reservation-refinement"
103  //
104  // The `Resource` objects can be in any of the valid resource formats:
105  // "pre-reservation-refinement", "post-reservation-refinement", "endpoint".
106  //
107  // All resources end up with the `Resource.reservations` field set,
108  // and the `Resource.role` and `Resource.reservation` fields unset.
109  //
110  // If the `Resource` objects are already in the "post-reservation-refinement"
111  // format, this is a no-op.
112  //
113  // We convert the resources to the "post-reservation-refinement" format,
114  // for example, when a master receives a message from an agent without
115  // the RESERVATION_REFINEMENT capability. This allows a component
116  // (e.g. master) code to deal with a canonical format to simplify the code.
118 
119  // "post-reservation-refinement" -> "endpoint"
120  //
121  // This is a special case for endpoints, which injects
122  // the "pre-reservation-refinement" format.
123  //
124  // The `Resource` objects must be in the "post-reservation-refinement" format.
125  //
126  // All resources continue to have the `Resource.reservations` field set.
127  // The `Resource` objects without refined reservations end up with the
128  // `Resource.role` and `Resource.reservation` fields set, and the objects
129  // with refined reservations have them unset.
130  //
131  // We inject the resources with the "pre-reservation-refinement" format to
132  // enable backward compatibility with external tooling. If the master has been
133  // upgraded to a version that supports reservation refinement but no refined
134  // reservations have been made, the endpoints will return the data in both new
135  // and old formats to maximize backward compatibility. However, once
136  // a reservation refinement is made to a resource, that resource is only
137  // returned in the new format.
139 };
140 
141 
142 // Converts the given `Resource` to the specified `ResourceFormat`.
143 //
144 // See the "Resource Format" section in `mesos.proto` for more details.
145 // See the `ResourceFormat` enum above for more details.
146 void convertResourceFormat(Resource* resource, ResourceFormat format);
147 
148 
149 // Converts the given `Resource`s to the specified `ResourceFormat`.
151  google::protobuf::RepeatedPtrField<Resource>* resources,
153 
154 
155 // Converts the given `Resource`s to the specified `ResourceFormat`.
157  std::vector<Resource>* resources,
159 
160 
161 // Convert any resources contained in the given message(s)
162 // to the "post-reservation-refinement" format.
163 void upgradeResource(Resource* resource);
164 
165 
166 void upgradeResources(google::protobuf::RepeatedPtrField<Resource>* resources);
167 
168 
169 void upgradeResources(std::vector<Resource>* resources);
170 
171 
172 void upgradeResources(google::protobuf::Message* message);
173 
174 
175 // Convert the resources in the given `Operation` to the
176 // "post-reservation-refinement" format from any format
177 // ("pre-", "post-" or "endpoint") if all of the resources are valid.
178 // Returns an `Error` if there are any invalid resources present;
179 // in this case, all resources are left unchanged.
180 // NOTE: The validate and upgrade steps are bundled because currently
181 // it would be an error to validate but not upgrade or to upgrade
182 // without validating.
184 
185 
186 // Convert any resources contained in the given message(s)
187 // to the "pre-reservation-refinement" format, if possible.
188 //
189 // These functions do not provide "all-or-nothing" semantics.
190 // The resources are downgraded to "pre-" format until either
191 // (1) there are no more resources, or
192 // (2) a non-downgradable resource is encountered.
193 //
194 // For (1), `Nothing` is returned.
195 // For (2), `Error` is returned, and the rest of the resources are untouched.
196 //
197 // This implies that components that have refined resources created cannot
198 // be downgraded to a version that does not support reservation refinement.
199 Try<Nothing> downgradeResource(Resource* resource);
200 
201 
203  google::protobuf::RepeatedPtrField<Resource>* resources);
204 
205 
206 Try<Nothing> downgradeResources(std::vector<Resource>* resources);
207 
208 
209 Try<Nothing> downgradeResources(google::protobuf::Message* message);
210 
211 
212 } // namespace mesos {
213 
214 #endif // __RESOURCES_UTILS_HPP__
Try< Nothing > downgradeResources(google::protobuf::RepeatedPtrField< Resource > *resources)
Definition: resources_utils.hpp:117
Definition: try.hpp:34
void convertResourceFormat(Resource *resource, ResourceFormat format)
Operation
Definition: cgroups.hpp:441
Definition: result.hpp:40
void upgradeResources(google::protobuf::RepeatedPtrField< Resource > *resources)
Definition: resources_utils.hpp:98
Definition: resources_utils.hpp:138
Result< ResourceProviderID > getResourceProviderId(const Offer::Operation &operation)
bool needCheckpointing(const Resource &resource)
Try< Resources > applyCheckpointedResources(const Resources &resources, const Resources &checkpointedResources)
void upgradeResource(Resource *resource)
Try< std::string > format(const std::string &fmt, va_list args)
Definition: format.hpp:68
Try< std::vector< ResourceConversion > > getResourceConversions(const Offer::Operation &operation)
Option< Error > validateAndUpgradeResources(Offer::Operation *operation)
Try< Nothing > downgradeResource(Resource *resource)
ResourceFormat
Definition: resources_utils.hpp:84