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 */
018package org.apache.hadoop.yarn.api.records;
019
020import org.apache.hadoop.classification.InterfaceAudience.Private;
021import org.apache.hadoop.classification.InterfaceAudience.Public;
022import org.apache.hadoop.classification.InterfaceStability.Evolving;
023import org.apache.hadoop.classification.InterfaceStability.Unstable;
024import org.apache.hadoop.yarn.util.Records;
025
026/**
027 * 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} (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.
035 * <p>
036 * 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.
041 * <p>
042 * 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.
046 * <p>
047 * Each preemption message reflects the RM's current understanding of the
048 * cluster state, so a request to return <em>N</em> 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.
053 * <p>
054 * 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.
057 */
058@Public
059@Evolving
060public 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}