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