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.ContainerStatus; 032 import org.apache.hadoop.yarn.api.records.NMToken; 033 import org.apache.hadoop.yarn.api.records.NodeReport; 034 import org.apache.hadoop.yarn.api.records.PreemptionMessage; 035 import org.apache.hadoop.yarn.api.records.Resource; 036 import org.apache.hadoop.yarn.util.Records; 037 038 /** 039 * <p>The response sent by the <code>ResourceManager</code> the 040 * <code>ApplicationMaster</code> during resource negotiation.</p> 041 * 042 * <p>The response, includes: 043 * <ul> 044 * <li>Response ID to track duplicate responses.</li> 045 * <li> 046 * An AMCommand sent by ResourceManager to let the <code>ApplicationMaster</code> 047 * take some actions (resync, shutdown etc.). 048 * <li>A list of newly allocated {@link Container}.</li> 049 * <li>A list of completed {@link Container}s' statuses.</li> 050 * <li> 051 * The available headroom for resources in the cluster for the 052 * application. 053 * </li> 054 * <li>A list of nodes whose status has been updated.</li> 055 * <li>The number of available nodes in a cluster.</li> 056 * <li>A description of resources requested back by the cluster</li> 057 * </ul> 058 * </p> 059 * 060 * @see ApplicationMasterProtocol#allocate(AllocateRequest) 061 */ 062 @Public 063 @Stable 064 public abstract class AllocateResponse { 065 066 @Public 067 @Stable 068 public static AllocateResponse newInstance(int responseId, 069 List<ContainerStatus> completedContainers, 070 List<Container> allocatedContainers, List<NodeReport> updatedNodes, 071 Resource availResources, AMCommand command, int numClusterNodes, 072 PreemptionMessage preempt, List<NMToken> nmTokens) { 073 AllocateResponse response = Records.newRecord(AllocateResponse.class); 074 response.setNumClusterNodes(numClusterNodes); 075 response.setResponseId(responseId); 076 response.setCompletedContainersStatuses(completedContainers); 077 response.setAllocatedContainers(allocatedContainers); 078 response.setUpdatedNodes(updatedNodes); 079 response.setAvailableResources(availResources); 080 response.setAMCommand(command); 081 response.setPreemptionMessage(preempt); 082 response.setNMTokens(nmTokens); 083 return response; 084 } 085 086 /** 087 * If the <code>ResourceManager</code> needs the 088 * <code>ApplicationMaster</code> to take some action then it will send an 089 * AMCommand to the <code>ApplicationMaster</code>. See <code>AMCommand</code> 090 * for details on commands and actions for them. 091 * @return <code>AMCommand</code> if the <code>ApplicationMaster</code> should 092 * take action, <code>null</code> otherwise 093 * @see AMCommand 094 */ 095 @Public 096 @Stable 097 public abstract AMCommand getAMCommand(); 098 099 @Private 100 @Unstable 101 public abstract void setAMCommand(AMCommand command); 102 103 /** 104 * Get the <em>last response id</em>. 105 * @return <em>last response id</em> 106 */ 107 @Public 108 @Stable 109 public abstract int getResponseId(); 110 111 @Private 112 @Unstable 113 public abstract void setResponseId(int responseId); 114 115 /** 116 * Get the list of <em>newly allocated</em> <code>Container</code> by the 117 * <code>ResourceManager</code>. 118 * @return list of <em>newly allocated</em> <code>Container</code> 119 */ 120 @Public 121 @Stable 122 public abstract List<Container> getAllocatedContainers(); 123 124 /** 125 * Set the list of <em>newly allocated</em> <code>Container</code> by the 126 * <code>ResourceManager</code>. 127 * @param containers list of <em>newly allocated</em> <code>Container</code> 128 */ 129 @Private 130 @Unstable 131 public abstract void setAllocatedContainers(List<Container> containers); 132 133 /** 134 * Get the <em>available headroom</em> for resources in the cluster for the 135 * application. 136 * @return limit of available headroom for resources in the cluster for the 137 * application 138 */ 139 @Public 140 @Stable 141 public abstract Resource getAvailableResources(); 142 143 @Private 144 @Unstable 145 public abstract void setAvailableResources(Resource limit); 146 147 /** 148 * Get the list of <em>completed containers' statuses</em>. 149 * @return the list of <em>completed containers' statuses</em> 150 */ 151 @Public 152 @Stable 153 public abstract List<ContainerStatus> getCompletedContainersStatuses(); 154 155 @Private 156 @Unstable 157 public abstract void setCompletedContainersStatuses(List<ContainerStatus> containers); 158 159 /** 160 * Get the list of <em>updated <code>NodeReport</code>s</em>. Updates could 161 * be changes in health, availability etc of the nodes. 162 * @return The delta of updated nodes since the last response 163 */ 164 @Public 165 @Stable 166 public abstract List<NodeReport> getUpdatedNodes(); 167 168 @Private 169 @Unstable 170 public abstract void setUpdatedNodes(final List<NodeReport> updatedNodes); 171 172 /** 173 * Get the number of hosts available on the cluster. 174 * @return the available host count. 175 */ 176 @Public 177 @Stable 178 public abstract int getNumClusterNodes(); 179 180 @Private 181 @Unstable 182 public abstract void setNumClusterNodes(int numNodes); 183 184 /** 185 * <p>Get the description of containers owned by the AM, but requested back by 186 * the cluster. Note that the RM may have an inconsistent view of the 187 * resources owned by the AM. These messages are advisory, and the AM may 188 * elect to ignore them.<p> 189 * 190 * <p>The message is a snapshot of the resources the RM wants back from the AM. 191 * While demand persists, the RM will repeat its request; applications should 192 * not interpret each message as a request for <em>additional<em> 193 * resources on top of previous messages. Resources requested consistently 194 * over some duration may be forcibly killed by the RM.<p> 195 * 196 * @return A specification of the resources to reclaim from this AM. 197 */ 198 @Public 199 @Evolving 200 public abstract PreemptionMessage getPreemptionMessage(); 201 202 @Private 203 @Unstable 204 public abstract void setPreemptionMessage(PreemptionMessage request); 205 206 /** 207 * <p>Get the list of NMTokens required for communicating with NM. New NMTokens 208 * issued only if<p> 209 * <p>1) AM is receiving first container on underlying NodeManager.<br> 210 * OR<br> 211 * 2) NMToken master key rolled over in ResourceManager and AM is getting new 212 * container on the same underlying NodeManager.<p> 213 * <p>AM will receive one NMToken per NM irrespective of the number of containers 214 * issued on same NM. AM is expected to store these tokens until issued a 215 * new token for the same NM.<p> 216 */ 217 @Public 218 @Stable 219 public abstract List<NMToken> getNMTokens(); 220 221 @Private 222 @Unstable 223 public abstract void setNMTokens(List<NMToken> nmTokens); 224 }