001 /**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019 package org.apache.hadoop.yarn.api.protocolrecords;
020
021 import java.util.List;
022
023 import org.apache.hadoop.classification.InterfaceAudience.Private;
024 import org.apache.hadoop.classification.InterfaceAudience.Public;
025 import org.apache.hadoop.classification.InterfaceStability.Evolving;
026 import org.apache.hadoop.classification.InterfaceStability.Stable;
027 import org.apache.hadoop.classification.InterfaceStability.Unstable;
028 import org.apache.hadoop.yarn.api.ApplicationMasterProtocol;
029 import org.apache.hadoop.yarn.api.records.AMCommand;
030 import org.apache.hadoop.yarn.api.records.Container;
031 import org.apache.hadoop.yarn.api.records.ContainerResourceDecrease;
032 import org.apache.hadoop.yarn.api.records.ContainerResourceIncrease;
033 import org.apache.hadoop.yarn.api.records.ContainerStatus;
034 import org.apache.hadoop.yarn.api.records.NMToken;
035 import org.apache.hadoop.yarn.api.records.NodeReport;
036 import org.apache.hadoop.yarn.api.records.PreemptionMessage;
037 import org.apache.hadoop.yarn.api.records.Resource;
038 import org.apache.hadoop.yarn.api.records.Token;
039 import org.apache.hadoop.yarn.util.Records;
040
041 /**
042 * <p>The response sent by the <code>ResourceManager</code> the
043 * <code>ApplicationMaster</code> during resource negotiation.</p>
044 *
045 * <p>The response, includes:
046 * <ul>
047 * <li>Response ID to track duplicate responses.</li>
048 * <li>
049 * An AMCommand sent by ResourceManager to let the <code>ApplicationMaster</code>
050 * take some actions (resync, shutdown etc.).
051 * <li>A list of newly allocated {@link Container}.</li>
052 * <li>A list of completed {@link Container}s' statuses.</li>
053 * <li>
054 * The available headroom for resources in the cluster for the
055 * application.
056 * </li>
057 * <li>A list of nodes whose status has been updated.</li>
058 * <li>The number of available nodes in a cluster.</li>
059 * <li>A description of resources requested back by the cluster</li>
060 * <li>AMRMToken, if AMRMToken has been rolled over</li>
061 * </ul>
062 * </p>
063 *
064 * @see ApplicationMasterProtocol#allocate(AllocateRequest)
065 */
066 @Public
067 @Stable
068 public abstract class AllocateResponse {
069
070 @Public
071 @Stable
072 public static AllocateResponse newInstance(int responseId,
073 List<ContainerStatus> completedContainers,
074 List<Container> allocatedContainers, List<NodeReport> updatedNodes,
075 Resource availResources, AMCommand command, int numClusterNodes,
076 PreemptionMessage preempt, List<NMToken> nmTokens) {
077 AllocateResponse response = Records.newRecord(AllocateResponse.class);
078 response.setNumClusterNodes(numClusterNodes);
079 response.setResponseId(responseId);
080 response.setCompletedContainersStatuses(completedContainers);
081 response.setAllocatedContainers(allocatedContainers);
082 response.setUpdatedNodes(updatedNodes);
083 response.setAvailableResources(availResources);
084 response.setAMCommand(command);
085 response.setPreemptionMessage(preempt);
086 response.setNMTokens(nmTokens);
087 return response;
088 }
089
090 @Public
091 @Stable
092 public static AllocateResponse newInstance(int responseId,
093 List<ContainerStatus> completedContainers,
094 List<Container> allocatedContainers, List<NodeReport> updatedNodes,
095 Resource availResources, AMCommand command, int numClusterNodes,
096 PreemptionMessage preempt, List<NMToken> nmTokens,
097 List<ContainerResourceIncrease> increasedContainers,
098 List<ContainerResourceDecrease> decreasedContainers) {
099 AllocateResponse response = newInstance(responseId, completedContainers,
100 allocatedContainers, updatedNodes, availResources, command,
101 numClusterNodes, preempt, nmTokens);
102 response.setIncreasedContainers(increasedContainers);
103 response.setDecreasedContainers(decreasedContainers);
104 return response;
105 }
106
107 @Private
108 @Unstable
109 public static AllocateResponse newInstance(int responseId,
110 List<ContainerStatus> completedContainers,
111 List<Container> allocatedContainers, List<NodeReport> updatedNodes,
112 Resource availResources, AMCommand command, int numClusterNodes,
113 PreemptionMessage preempt, List<NMToken> nmTokens, Token amRMToken,
114 List<ContainerResourceIncrease> increasedContainers,
115 List<ContainerResourceDecrease> decreasedContainers) {
116 AllocateResponse response =
117 newInstance(responseId, completedContainers, allocatedContainers,
118 updatedNodes, availResources, command, numClusterNodes, preempt,
119 nmTokens, increasedContainers, decreasedContainers);
120 response.setAMRMToken(amRMToken);
121 return response;
122 }
123
124 /**
125 * If the <code>ResourceManager</code> needs the
126 * <code>ApplicationMaster</code> to take some action then it will send an
127 * AMCommand to the <code>ApplicationMaster</code>. See <code>AMCommand</code>
128 * for details on commands and actions for them.
129 * @return <code>AMCommand</code> if the <code>ApplicationMaster</code> should
130 * take action, <code>null</code> otherwise
131 * @see AMCommand
132 */
133 @Public
134 @Stable
135 public abstract AMCommand getAMCommand();
136
137 @Private
138 @Unstable
139 public abstract void setAMCommand(AMCommand command);
140
141 /**
142 * Get the <em>last response id</em>.
143 * @return <em>last response id</em>
144 */
145 @Public
146 @Stable
147 public abstract int getResponseId();
148
149 @Private
150 @Unstable
151 public abstract void setResponseId(int responseId);
152
153 /**
154 * Get the list of <em>newly allocated</em> <code>Container</code> by the
155 * <code>ResourceManager</code>.
156 * @return list of <em>newly allocated</em> <code>Container</code>
157 */
158 @Public
159 @Stable
160 public abstract List<Container> getAllocatedContainers();
161
162 /**
163 * Set the list of <em>newly allocated</em> <code>Container</code> by the
164 * <code>ResourceManager</code>.
165 * @param containers list of <em>newly allocated</em> <code>Container</code>
166 */
167 @Private
168 @Unstable
169 public abstract void setAllocatedContainers(List<Container> containers);
170
171 /**
172 * Get the <em>available headroom</em> for resources in the cluster for the
173 * application.
174 * @return limit of available headroom for resources in the cluster for the
175 * application
176 */
177 @Public
178 @Stable
179 public abstract Resource getAvailableResources();
180
181 @Private
182 @Unstable
183 public abstract void setAvailableResources(Resource limit);
184
185 /**
186 * Get the list of <em>completed containers' statuses</em>.
187 * @return the list of <em>completed containers' statuses</em>
188 */
189 @Public
190 @Stable
191 public abstract List<ContainerStatus> getCompletedContainersStatuses();
192
193 @Private
194 @Unstable
195 public abstract void setCompletedContainersStatuses(List<ContainerStatus> containers);
196
197 /**
198 * Get the list of <em>updated <code>NodeReport</code>s</em>. Updates could
199 * be changes in health, availability etc of the nodes.
200 * @return The delta of updated nodes since the last response
201 */
202 @Public
203 @Stable
204 public abstract List<NodeReport> getUpdatedNodes();
205
206 @Private
207 @Unstable
208 public abstract void setUpdatedNodes(final List<NodeReport> updatedNodes);
209
210 /**
211 * Get the number of hosts available on the cluster.
212 * @return the available host count.
213 */
214 @Public
215 @Stable
216 public abstract int getNumClusterNodes();
217
218 @Private
219 @Unstable
220 public abstract void setNumClusterNodes(int numNodes);
221
222 /**
223 * <p>Get the description of containers owned by the AM, but requested back by
224 * the cluster. Note that the RM may have an inconsistent view of the
225 * resources owned by the AM. These messages are advisory, and the AM may
226 * elect to ignore them.<p>
227 *
228 * <p>The message is a snapshot of the resources the RM wants back from the AM.
229 * While demand persists, the RM will repeat its request; applications should
230 * not interpret each message as a request for <em>additional<em>
231 * resources on top of previous messages. Resources requested consistently
232 * over some duration may be forcibly killed by the RM.<p>
233 *
234 * @return A specification of the resources to reclaim from this AM.
235 */
236 @Public
237 @Evolving
238 public abstract PreemptionMessage getPreemptionMessage();
239
240 @Private
241 @Unstable
242 public abstract void setPreemptionMessage(PreemptionMessage request);
243
244 /**
245 * <p>Get the list of NMTokens required for communicating with NM. New NMTokens
246 * issued only if<p>
247 * <p>1) AM is receiving first container on underlying NodeManager.<br>
248 * OR<br>
249 * 2) NMToken master key rolled over in ResourceManager and AM is getting new
250 * container on the same underlying NodeManager.<p>
251 * <p>AM will receive one NMToken per NM irrespective of the number of containers
252 * issued on same NM. AM is expected to store these tokens until issued a
253 * new token for the same NM.<p>
254 */
255 @Public
256 @Stable
257 public abstract List<NMToken> getNMTokens();
258
259 @Private
260 @Unstable
261 public abstract void setNMTokens(List<NMToken> nmTokens);
262
263 /**
264 * Get the list of newly increased containers by <code>ResourceManager</code>
265 */
266 @Public
267 @Stable
268 public abstract List<ContainerResourceIncrease> getIncreasedContainers();
269
270 /**
271 * Set the list of newly increased containers by <code>ResourceManager</code>
272 */
273 @Private
274 @Unstable
275 public abstract void setIncreasedContainers(
276 List<ContainerResourceIncrease> increasedContainers);
277
278 /**
279 * Get the list of newly decreased containers by <code>NodeManager</code>
280 */
281 @Public
282 @Stable
283 public abstract List<ContainerResourceDecrease> getDecreasedContainers();
284
285 /**
286 * Set the list of newly decreased containers by <code>NodeManager</code>
287 */
288 @Private
289 @Unstable
290 public abstract void setDecreasedContainers(
291 List<ContainerResourceDecrease> decreasedContainers);
292
293 /**
294 * The AMRMToken that belong to this attempt
295 *
296 * @return The AMRMToken that belong to this attempt
297 */
298 @Public
299 @Unstable
300 public abstract Token getAMRMToken();
301
302 @Private
303 @Unstable
304 public abstract void setAMRMToken(Token amRMToken);
305 }