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