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    }