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}