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 package org.apache.hadoop.yarn.api.records;
019
020 import org.apache.hadoop.classification.InterfaceAudience.Private;
021 import org.apache.hadoop.classification.InterfaceAudience.Public;
022 import org.apache.hadoop.classification.InterfaceStability.Evolving;
023 import org.apache.hadoop.classification.InterfaceStability.Unstable;
024 import org.apache.hadoop.yarn.util.Records;
025
026 /**
027 * <p>A {@link PreemptionMessage} is part of the RM-AM protocol, and it is used by
028 * the RM to specify resources that the RM wants to reclaim from this
029 * <code>ApplicationMaster</code> (AM). The AM receives a {@link
030 * StrictPreemptionContract} message encoding which containers the platform may
031 * forcibly kill, granting it an opportunity to checkpoint state or adjust its
032 * execution plan. The message may also include a {@link PreemptionContract}
033 * granting the AM more latitude in selecting which resources to return to the
034 * cluster.<p>
035 *
036 * <p>The AM should decode both parts of the message. The {@link
037 * StrictPreemptionContract} specifies particular allocations that the RM
038 * requires back. The AM can checkpoint containers' state, adjust its execution
039 * plan to move the computation, or take no action and hope that conditions that
040 * caused the RM to ask for the container will change.<p>
041 *
042 * <p>In contrast, the {@link PreemptionContract} also includes a description of
043 * resources with a set of containers. If the AM releases containers matching
044 * that profile, then the containers enumerated in {@link
045 * PreemptionContract#getContainers()} may not be killed.<p>
046 *
047 * <p>Each preemption message reflects the RM's current understanding of the
048 * cluster state, so a request to return <emph>N</emph> containers may not
049 * reflect containers the AM is releasing, recently exited containers the RM has
050 * yet to learn about, or new containers allocated before the message was
051 * generated. Conversely, an RM may request a different profile of containers in
052 * subsequent requests.<p>
053 *
054 * <p>The policy enforced by the RM is part of the scheduler. Generally, only
055 * containers that have been requested consistently should be killed, but the
056 * details are not specified.<p>
057 */
058 @Public
059 @Evolving
060 public abstract class PreemptionMessage {
061
062 @Private
063 @Unstable
064 public static PreemptionMessage newInstance(StrictPreemptionContract set,
065 PreemptionContract contract) {
066 PreemptionMessage message = Records.newRecord(PreemptionMessage.class);
067 message.setStrictContract(set);
068 message.setContract(contract);
069 return message;
070 }
071
072 /**
073 * @return Specific resources that may be killed by the
074 * <code>ResourceManager</code>
075 */
076 @Public
077 @Evolving
078 public abstract StrictPreemptionContract getStrictContract();
079
080 @Private
081 @Unstable
082 public abstract void setStrictContract(StrictPreemptionContract set);
083
084 /**
085 * @return Contract describing resources to return to the cluster.
086 */
087 @Public
088 @Evolving
089 public abstract PreemptionContract getContract();
090
091 @Private
092 @Unstable
093 public abstract void setContract(PreemptionContract contract);
094
095 }