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.hadoop.classification.InterfaceAudience.Public;
022import org.apache.hadoop.classification.InterfaceStability.Evolving;
023import org.apache.hadoop.classification.InterfaceStability.Stable;
024import org.apache.hadoop.yarn.api.ApplicationMasterProtocol;
025import 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
052public 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}