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    }