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