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 019package org.apache.hadoop.yarn.api.records; 020 021import org.apache.commons.lang.NotImplementedException; 022import org.apache.hadoop.classification.InterfaceStability.Evolving; 023import org.apache.hadoop.classification.InterfaceAudience.Public; 024import org.apache.hadoop.classification.InterfaceStability.Stable; 025import org.apache.hadoop.yarn.api.ApplicationMasterProtocol; 026import org.apache.hadoop.yarn.util.Records; 027 028 029/** 030 * <p><code>Resource</code> models a set of computer resources in the 031 * cluster.</p> 032 * 033 * <p>Currently it models both <em>memory</em> and <em>CPU</em>.</p> 034 * 035 * <p>The unit for memory is megabytes. CPU is modeled with virtual cores 036 * (vcores), a unit for expressing parallelism. A node's capacity should 037 * be configured with virtual cores equal to its number of physical cores. A 038 * container should be requested with the number of cores it can saturate, i.e. 039 * the average number of threads it expects to have runnable at a time.</p> 040 * 041 * <p>Virtual cores take integer values and thus currently CPU-scheduling is 042 * very coarse. A complementary axis for CPU requests that represents processing 043 * power will likely be added in the future to enable finer-grained resource 044 * configuration.</p> 045 * 046 * <p>Typically, applications request <code>Resource</code> of suitable 047 * capability to run their component tasks.</p> 048 * 049 * @see ResourceRequest 050 * @see ApplicationMasterProtocol#allocate(org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest) 051 */ 052@Public 053@Stable 054public abstract class Resource implements Comparable<Resource> { 055 056 @Public 057 @Stable 058 public static Resource newInstance(int memory, int vCores) { 059 Resource resource = Records.newRecord(Resource.class); 060 resource.setMemorySize(memory); 061 resource.setVirtualCores(vCores); 062 return resource; 063 } 064 065 @Public 066 @Stable 067 public static Resource newInstance(long memory, int vCores) { 068 Resource resource = Records.newRecord(Resource.class); 069 resource.setMemorySize(memory); 070 resource.setVirtualCores(vCores); 071 return resource; 072 } 073 074 /** 075 * This method is DEPRECATED: 076 * Use {@link Resource#getMemorySize()} instead 077 * 078 * Get <em>memory</em> of the resource. 079 * @return <em>memory</em> of the resource 080 */ 081 @Public 082 @Deprecated 083 public abstract int getMemory(); 084 085 /** 086 * Get <em>memory</em> of the resource. 087 * @return <em>memory</em> of the resource 088 */ 089 @Public 090 @Stable 091 public long getMemorySize() { 092 throw new NotImplementedException( 093 "This method is implemented by ResourcePBImpl"); 094 } 095 096 /** 097 * Set <em>memory</em> of the resource. 098 * @param memory <em>memory</em> of the resource 099 */ 100 @Public 101 @Deprecated 102 public abstract void setMemory(int memory); 103 104 /** 105 * Set <em>memory</em> of the resource. 106 * @param memory <em>memory</em> of the resource 107 */ 108 @Public 109 @Stable 110 public void setMemorySize(long memory) { 111 throw new NotImplementedException( 112 "This method is implemented by ResourcePBImpl"); 113 } 114 115 116 /** 117 * Get <em>number of virtual cpu cores</em> of the resource. 118 * 119 * Virtual cores are a unit for expressing CPU parallelism. A node's capacity 120 * should be configured with virtual cores equal to its number of physical cores. 121 * A container should be requested with the number of cores it can saturate, i.e. 122 * the average number of threads it expects to have runnable at a time. 123 * 124 * @return <em>num of virtual cpu cores</em> of the resource 125 */ 126 @Public 127 @Evolving 128 public abstract int getVirtualCores(); 129 130 /** 131 * Set <em>number of virtual cpu cores</em> of the resource. 132 * 133 * Virtual cores are a unit for expressing CPU parallelism. A node's capacity 134 * should be configured with virtual cores equal to its number of physical cores. 135 * A container should be requested with the number of cores it can saturate, i.e. 136 * the average number of threads it expects to have runnable at a time. 137 * 138 * @param vCores <em>number of virtual cpu cores</em> of the resource 139 */ 140 @Public 141 @Evolving 142 public abstract void setVirtualCores(int vCores); 143 144 @Override 145 public int hashCode() { 146 final int prime = 263167; 147 148 int result = (int) (939769357 149 + getMemorySize()); // prime * result = 939769357 initially 150 result = prime * result + getVirtualCores(); 151 return result; 152 } 153 154 @Override 155 public boolean equals(Object obj) { 156 if (this == obj) 157 return true; 158 if (obj == null) 159 return false; 160 if (!(obj instanceof Resource)) 161 return false; 162 Resource other = (Resource) obj; 163 if (getMemorySize() != other.getMemorySize() || 164 getVirtualCores() != other.getVirtualCores()) { 165 return false; 166 } 167 return true; 168 } 169 170 @Override 171 public String toString() { 172 return "<memory:" + getMemorySize() + ", vCores:" + getVirtualCores() + ">"; 173 } 174}