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 * <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 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}