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 019package org.apache.hadoop.yarn.api.protocolrecords; 020 021import java.util.ArrayList; 022import java.util.List; 023 024import org.apache.hadoop.classification.InterfaceAudience.Private; 025import org.apache.hadoop.classification.InterfaceAudience.Public; 026import org.apache.hadoop.classification.InterfaceStability.Evolving; 027import org.apache.hadoop.classification.InterfaceStability.Stable; 028import org.apache.hadoop.classification.InterfaceStability.Unstable; 029import org.apache.hadoop.yarn.api.ApplicationMasterProtocol; 030import org.apache.hadoop.yarn.api.records.AMCommand; 031import org.apache.hadoop.yarn.api.records.Container; 032import org.apache.hadoop.yarn.api.records.ContainerResourceDecrease; 033import org.apache.hadoop.yarn.api.records.ContainerResourceIncrease; 034import org.apache.hadoop.yarn.api.records.ContainerStatus; 035import org.apache.hadoop.yarn.api.records.NMToken; 036import org.apache.hadoop.yarn.api.records.NodeReport; 037import org.apache.hadoop.yarn.api.records.PreemptionMessage; 038import org.apache.hadoop.yarn.api.records.Priority; 039import org.apache.hadoop.yarn.api.records.Resource; 040import org.apache.hadoop.yarn.api.records.Token; 041import org.apache.hadoop.yarn.api.records.UpdateContainerError; 042import org.apache.hadoop.yarn.api.records.UpdatedContainer; 043import org.apache.hadoop.yarn.util.Records; 044 045/** 046 * The response sent by the <code>ResourceManager</code> the 047 * <code>ApplicationMaster</code> during resource negotiation. 048 * <p> 049 * The response, includes: 050 * <ul> 051 * <li>Response ID to track duplicate responses.</li> 052 * <li> 053 * An AMCommand sent by ResourceManager to let the 054 * {@code ApplicationMaster} take some actions (resync, shutdown etc.). 055 * </li> 056 * <li>A list of newly allocated {@link Container}.</li> 057 * <li>A list of completed {@link Container}s' statuses.</li> 058 * <li> 059 * The available headroom for resources in the cluster for the 060 * application. 061 * </li> 062 * <li>A list of nodes whose status has been updated.</li> 063 * <li>The number of available nodes in a cluster.</li> 064 * <li>A description of resources requested back by the cluster</li> 065 * <li>AMRMToken, if AMRMToken has been rolled over</li> 066 * <li> 067 * A list of {@link Container} representing the containers 068 * whose resource has been increased. 069 * </li> 070 * <li> 071 * A list of {@link Container} representing the containers 072 * whose resource has been decreased. 073 * </li> 074 * </ul> 075 * 076 * @see ApplicationMasterProtocol#allocate(AllocateRequest) 077 */ 078@Public 079@Stable 080public abstract class AllocateResponse { 081 082 @Public 083 @Stable 084 public static AllocateResponse newInstance(int responseId, 085 List<ContainerStatus> completedContainers, 086 List<Container> allocatedContainers, List<NodeReport> updatedNodes, 087 Resource availResources, AMCommand command, int numClusterNodes, 088 PreemptionMessage preempt, List<NMToken> nmTokens) { 089 AllocateResponse response = Records.newRecord(AllocateResponse.class); 090 response.setNumClusterNodes(numClusterNodes); 091 response.setResponseId(responseId); 092 response.setCompletedContainersStatuses(completedContainers); 093 response.setAllocatedContainers(allocatedContainers); 094 response.setUpdatedNodes(updatedNodes); 095 response.setAvailableResources(availResources); 096 response.setAMCommand(command); 097 response.setPreemptionMessage(preempt); 098 response.setNMTokens(nmTokens); 099 return response; 100 } 101 102 /** 103 * Use {@link AllocateResponse#newInstance(int, List, List, List, Resource, 104 * AMCommand, int, PreemptionMessage, List, Token, List)} instead 105 * @param responseId responseId 106 * @param completedContainers completedContainers 107 * @param allocatedContainers allocatedContainers 108 * @param updatedNodes updatedNodes 109 * @param availResources availResources 110 * @param command command 111 * @param numClusterNodes numClusterNodes 112 * @param preempt preempt 113 * @param nmTokens nmTokens 114 * @param increasedContainers increasedContainers 115 * @param decreasedContainers decreasedContainers 116 * @return AllocateResponse 117 */ 118 @Deprecated 119 public static AllocateResponse newInstance(int responseId, 120 List<ContainerStatus> completedContainers, 121 List<Container> allocatedContainers, List<NodeReport> updatedNodes, 122 Resource availResources, AMCommand command, int numClusterNodes, 123 PreemptionMessage preempt, List<NMToken> nmTokens, 124 List<ContainerResourceIncrease> increasedContainers, 125 List<ContainerResourceDecrease> decreasedContainers) { 126 return newInstance(responseId, completedContainers, allocatedContainers, 127 updatedNodes, availResources, command, numClusterNodes, preempt, 128 nmTokens); 129 } 130 131 @Public 132 @Unstable 133 public static AllocateResponse newInstance(int responseId, 134 List<ContainerStatus> completedContainers, 135 List<Container> allocatedContainers, List<NodeReport> updatedNodes, 136 Resource availResources, AMCommand command, int numClusterNodes, 137 PreemptionMessage preempt, List<NMToken> nmTokens, 138 List<UpdatedContainer> updatedContainers) { 139 AllocateResponse response = newInstance(responseId, completedContainers, 140 allocatedContainers, updatedNodes, availResources, command, 141 numClusterNodes, preempt, nmTokens); 142 response.setUpdatedContainers(updatedContainers); 143 return response; 144 } 145 146 @Private 147 @Unstable 148 public static AllocateResponse newInstance(int responseId, 149 List<ContainerStatus> completedContainers, 150 List<Container> allocatedContainers, List<NodeReport> updatedNodes, 151 Resource availResources, AMCommand command, int numClusterNodes, 152 PreemptionMessage preempt, List<NMToken> nmTokens, Token amRMToken, 153 List<UpdatedContainer> updatedContainers) { 154 AllocateResponse response = 155 newInstance(responseId, completedContainers, allocatedContainers, 156 updatedNodes, availResources, command, numClusterNodes, preempt, 157 nmTokens, updatedContainers); 158 response.setAMRMToken(amRMToken); 159 return response; 160 } 161 162 /** 163 * If the <code>ResourceManager</code> needs the 164 * <code>ApplicationMaster</code> to take some action then it will send an 165 * AMCommand to the <code>ApplicationMaster</code>. See <code>AMCommand</code> 166 * for details on commands and actions for them. 167 * @return <code>AMCommand</code> if the <code>ApplicationMaster</code> should 168 * take action, <code>null</code> otherwise 169 * @see AMCommand 170 */ 171 @Public 172 @Stable 173 public abstract AMCommand getAMCommand(); 174 175 @Private 176 @Unstable 177 public abstract void setAMCommand(AMCommand command); 178 179 /** 180 * Get the <em>last response id</em>. 181 * @return <em>last response id</em> 182 */ 183 @Public 184 @Stable 185 public abstract int getResponseId(); 186 187 @Private 188 @Unstable 189 public abstract void setResponseId(int responseId); 190 191 /** 192 * Get the list of <em>newly allocated</em> <code>Container</code> by the 193 * <code>ResourceManager</code>. 194 * @return list of <em>newly allocated</em> <code>Container</code> 195 */ 196 @Public 197 @Stable 198 public abstract List<Container> getAllocatedContainers(); 199 200 /** 201 * Set the list of <em>newly allocated</em> <code>Container</code> by the 202 * <code>ResourceManager</code>. 203 * @param containers list of <em>newly allocated</em> <code>Container</code> 204 */ 205 @Private 206 @Unstable 207 public abstract void setAllocatedContainers(List<Container> containers); 208 209 /** 210 * Get the <em>available headroom</em> for resources in the cluster for the 211 * application. 212 * @return limit of available headroom for resources in the cluster for the 213 * application 214 */ 215 @Public 216 @Stable 217 public abstract Resource getAvailableResources(); 218 219 @Private 220 @Unstable 221 public abstract void setAvailableResources(Resource limit); 222 223 /** 224 * Get the list of <em>completed containers' statuses</em>. 225 * @return the list of <em>completed containers' statuses</em> 226 */ 227 @Public 228 @Stable 229 public abstract List<ContainerStatus> getCompletedContainersStatuses(); 230 231 @Private 232 @Unstable 233 public abstract void setCompletedContainersStatuses(List<ContainerStatus> containers); 234 235 /** 236 * Get the list of <em>updated <code>NodeReport</code>s</em>. Updates could 237 * be changes in health, availability etc of the nodes. 238 * @return The delta of updated nodes since the last response 239 */ 240 @Public 241 @Stable 242 public abstract List<NodeReport> getUpdatedNodes(); 243 244 @Private 245 @Unstable 246 public abstract void setUpdatedNodes(final List<NodeReport> updatedNodes); 247 248 /** 249 * Get the number of hosts available on the cluster. 250 * @return the available host count. 251 */ 252 @Public 253 @Stable 254 public abstract int getNumClusterNodes(); 255 256 @Private 257 @Unstable 258 public abstract void setNumClusterNodes(int numNodes); 259 260 /** 261 * Get the description of containers owned by the AM, but requested back by 262 * the cluster. Note that the RM may have an inconsistent view of the 263 * resources owned by the AM. These messages are advisory, and the AM may 264 * elect to ignore them. 265 * <p> 266 * The message is a snapshot of the resources the RM wants back from the AM. 267 * While demand persists, the RM will repeat its request; applications should 268 * not interpret each message as a request for <em>additional</em> 269 * resources on top of previous messages. Resources requested consistently 270 * over some duration may be forcibly killed by the RM. 271 * 272 * @return A specification of the resources to reclaim from this AM. 273 */ 274 @Public 275 @Evolving 276 public abstract PreemptionMessage getPreemptionMessage(); 277 278 @Private 279 @Unstable 280 public abstract void setPreemptionMessage(PreemptionMessage request); 281 282 /** 283 * Get the list of NMTokens required for communicating with NM. New NMTokens 284 * issued only if 285 * <p> 286 * 1) AM is receiving first container on underlying NodeManager.<br> 287 * OR<br> 288 * 2) NMToken master key rolled over in ResourceManager and AM is getting new 289 * container on the same underlying NodeManager. 290 * <p> 291 * AM will receive one NMToken per NM irrespective of the number of containers 292 * issued on same NM. AM is expected to store these tokens until issued a 293 * new token for the same NM. 294 */ 295 @Public 296 @Stable 297 public abstract List<NMToken> getNMTokens(); 298 299 @Private 300 @Unstable 301 public abstract void setNMTokens(List<NMToken> nmTokens); 302 303 /** 304 * Get the list of newly updated containers by 305 * <code>ResourceManager</code>. 306 */ 307 @Public 308 @Unstable 309 public abstract List<UpdatedContainer> getUpdatedContainers(); 310 311 /** 312 * Set the list of newly updated containers by 313 * <code>ResourceManager</code>. 314 * 315 * @param updatedContainers List of Updated Containers. 316 */ 317 @Private 318 @Unstable 319 public abstract void setUpdatedContainers( 320 List<UpdatedContainer> updatedContainers); 321 322 /** 323 * The AMRMToken that belong to this attempt 324 * 325 * @return The AMRMToken that belong to this attempt 326 */ 327 @Public 328 @Unstable 329 public abstract Token getAMRMToken(); 330 331 @Private 332 @Unstable 333 public abstract void setAMRMToken(Token amRMToken); 334 335 /** 336 * Priority of the application 337 * 338 * @return get application priority 339 */ 340 @Public 341 @Unstable 342 public abstract Priority getApplicationPriority(); 343 344 @Private 345 @Unstable 346 public abstract void setApplicationPriority(Priority priority); 347 348 /** 349 * Get the list of container update errors to inform the 350 * Application Master about the container updates that could not be 351 * satisfied due to error. 352 * 353 * @return List of Update Container Errors. 354 */ 355 @Public 356 @Unstable 357 public List<UpdateContainerError> getUpdateErrors() { 358 return new ArrayList<>(); 359 } 360 361 /** 362 * Set the list of container update errors to inform the 363 * Application Master about the container updates that could not be 364 * satisfied due to error. 365 * @param updateErrors list of <code>UpdateContainerError</code> for 366 * containers updates requests that were in error 367 */ 368 @Public 369 @Unstable 370 public void setUpdateErrors(List<UpdateContainerError> updateErrors) { 371 } 372 373 /** 374 * Use {@link AllocateResponse#getUpdatedContainers()} instead 375 * @return null 376 */ 377 @Deprecated 378 public abstract List<ContainerResourceIncrease> getIncreasedContainers(); 379 380 /** 381 * Use {@link AllocateResponse#getUpdatedContainers()} instead 382 * @return null 383 */ 384 @Deprecated 385 public abstract List<ContainerResourceDecrease> getDecreasedContainers(); 386}