1 /** 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 19 package org.apache.hadoop.yarn.server.resourcemanager.scheduler.capacity; 20 21 import java.io.IOException; 22 import java.util.Collection; 23 import java.util.List; 24 25 import org.apache.hadoop.classification.InterfaceAudience.Private; 26 import org.apache.hadoop.classification.InterfaceStability.Stable; 27 import org.apache.hadoop.security.AccessControlException; 28 import org.apache.hadoop.security.UserGroupInformation; 29 import org.apache.hadoop.yarn.api.records.ApplicationAttemptId; 30 import org.apache.hadoop.yarn.api.records.ApplicationId; 31 import org.apache.hadoop.yarn.api.records.ContainerStatus; 32 import org.apache.hadoop.yarn.api.records.QueueACL; 33 import org.apache.hadoop.yarn.api.records.QueueState; 34 import org.apache.hadoop.yarn.api.records.Resource; 35 import org.apache.hadoop.yarn.server.resourcemanager.rmcontainer.RMContainer; 36 import org.apache.hadoop.yarn.server.resourcemanager.rmcontainer.RMContainerEventType; 37 import org.apache.hadoop.yarn.server.resourcemanager.scheduler.ActiveUsersManager; 38 import org.apache.hadoop.yarn.server.resourcemanager.scheduler.ResourceLimits; 39 import org.apache.hadoop.yarn.server.resourcemanager.scheduler.ResourceUsage; 40 import org.apache.hadoop.yarn.server.resourcemanager.scheduler.common.fica.FiCaSchedulerApp; 41 import org.apache.hadoop.yarn.server.resourcemanager.scheduler.common.fica.FiCaSchedulerNode; 42 43 /** 44 * <code>CSQueue</code> represents a node in the tree of 45 * hierarchical queues in the {@link CapacityScheduler}. 46 */ 47 @Stable 48 @Private 49 public interface CSQueue 50 extends org.apache.hadoop.yarn.server.resourcemanager.scheduler.Queue { 51 /** 52 * Get the parent <code>Queue</code>. 53 * @return the parent queue 54 */ getParent()55 public CSQueue getParent(); 56 57 /** 58 * Set the parent <code>Queue</code>. 59 * @param newParentQueue new parent queue 60 */ setParent(CSQueue newParentQueue)61 public void setParent(CSQueue newParentQueue); 62 63 /** 64 * Get the queue name. 65 * @return the queue name 66 */ getQueueName()67 public String getQueueName(); 68 69 /** 70 * Get the full name of the queue, including the heirarchy. 71 * @return the full name of the queue 72 */ getQueuePath()73 public String getQueuePath(); 74 75 /** 76 * Get the configured <em>capacity</em> of the queue. 77 * @return configured queue capacity 78 */ getCapacity()79 public float getCapacity(); 80 81 /** 82 * Get capacity of the parent of the queue as a function of the 83 * cumulative capacity in the cluster. 84 * @return capacity of the parent of the queue as a function of the 85 * cumulative capacity in the cluster 86 */ getAbsoluteCapacity()87 public float getAbsoluteCapacity(); 88 89 /** 90 * Get the configured maximum-capacity of the queue. 91 * @return the configured maximum-capacity of the queue 92 */ getMaximumCapacity()93 public float getMaximumCapacity(); 94 95 /** 96 * Get maximum-capacity of the queue as a funciton of the cumulative capacity 97 * of the cluster. 98 * @return maximum-capacity of the queue as a funciton of the cumulative capacity 99 * of the cluster 100 */ getAbsoluteMaximumCapacity()101 public float getAbsoluteMaximumCapacity(); 102 103 /** 104 * Get the current absolute used capacity of the queue 105 * relative to the entire cluster. 106 * @return queue absolute used capacity 107 */ getAbsoluteUsedCapacity()108 public float getAbsoluteUsedCapacity(); 109 110 /** 111 * Set used capacity of the queue. 112 * @param usedCapacity 113 * used capacity of the queue 114 */ setUsedCapacity(float usedCapacity)115 public void setUsedCapacity(float usedCapacity); 116 117 /** 118 * Set absolute used capacity of the queue. 119 * @param absUsedCapacity 120 * absolute used capacity of the queue 121 */ setAbsoluteUsedCapacity(float absUsedCapacity)122 public void setAbsoluteUsedCapacity(float absUsedCapacity); 123 124 /** 125 * Get the current used capacity of nodes without label(s) of the queue 126 * and it's children (if any). 127 * @return queue used capacity 128 */ getUsedCapacity()129 public float getUsedCapacity(); 130 131 /** 132 * Get the currently utilized resources which allocated at nodes without any 133 * labels in the cluster by the queue and children (if any). 134 * 135 * @return used resources by the queue and it's children 136 */ getUsedResources()137 public Resource getUsedResources(); 138 139 /** 140 * Get the current run-state of the queue 141 * @return current run-state 142 */ getState()143 public QueueState getState(); 144 145 /** 146 * Get child queues 147 * @return child queues 148 */ getChildQueues()149 public List<CSQueue> getChildQueues(); 150 151 /** 152 * Check if the <code>user</code> has permission to perform the operation 153 * @param acl ACL 154 * @param user user 155 * @return <code>true</code> if the user has the permission, 156 * <code>false</code> otherwise 157 */ hasAccess(QueueACL acl, UserGroupInformation user)158 public boolean hasAccess(QueueACL acl, UserGroupInformation user); 159 160 /** 161 * Submit a new application to the queue. 162 * @param applicationId the applicationId of the application being submitted 163 * @param user user who submitted the application 164 * @param queue queue to which the application is submitted 165 */ submitApplication(ApplicationId applicationId, String user, String queue)166 public void submitApplication(ApplicationId applicationId, String user, 167 String queue) throws AccessControlException; 168 169 /** 170 * Submit an application attempt to the queue. 171 */ submitApplicationAttempt(FiCaSchedulerApp application, String userName)172 public void submitApplicationAttempt(FiCaSchedulerApp application, 173 String userName); 174 175 /** 176 * An application submitted to this queue has finished. 177 * @param applicationId 178 * @param user user who submitted the application 179 */ finishApplication(ApplicationId applicationId, String user)180 public void finishApplication(ApplicationId applicationId, String user); 181 182 /** 183 * An application attempt submitted to this queue has finished. 184 */ finishApplicationAttempt(FiCaSchedulerApp application, String queue)185 public void finishApplicationAttempt(FiCaSchedulerApp application, 186 String queue); 187 188 /** 189 * Assign containers to applications in the queue or it's children (if any). 190 * @param clusterResource the resource of the cluster. 191 * @param node node on which resources are available 192 * @param resourceLimits how much overall resource of this queue can use. 193 * @return the assignment 194 */ assignContainers(Resource clusterResource, FiCaSchedulerNode node, ResourceLimits resourceLimits)195 public CSAssignment assignContainers(Resource clusterResource, 196 FiCaSchedulerNode node, ResourceLimits resourceLimits); 197 198 /** 199 * A container assigned to the queue has completed. 200 * @param clusterResource the resource of the cluster 201 * @param application application to which the container was assigned 202 * @param node node on which the container completed 203 * @param container completed container, 204 * <code>null</code> if it was just a reservation 205 * @param containerStatus <code>ContainerStatus</code> for the completed 206 * container 207 * @param childQueue <code>CSQueue</code> to reinsert in childQueues 208 * @param event event to be sent to the container 209 * @param sortQueues indicates whether it should re-sort the queues 210 */ completedContainer(Resource clusterResource, FiCaSchedulerApp application, FiCaSchedulerNode node, RMContainer container, ContainerStatus containerStatus, RMContainerEventType event, CSQueue childQueue, boolean sortQueues)211 public void completedContainer(Resource clusterResource, 212 FiCaSchedulerApp application, FiCaSchedulerNode node, 213 RMContainer container, ContainerStatus containerStatus, 214 RMContainerEventType event, CSQueue childQueue, 215 boolean sortQueues); 216 217 /** 218 * Get the number of applications in the queue. 219 * @return number of applications 220 */ getNumApplications()221 public int getNumApplications(); 222 223 224 /** 225 * Reinitialize the queue. 226 * @param newlyParsedQueue new queue to re-initalize from 227 * @param clusterResource resources in the cluster 228 */ reinitialize(CSQueue newlyParsedQueue, Resource clusterResource)229 public void reinitialize(CSQueue newlyParsedQueue, Resource clusterResource) 230 throws IOException; 231 232 /** 233 * Update the cluster resource for queues as we add/remove nodes 234 * @param clusterResource the current cluster resource 235 * @param resourceLimits the current ResourceLimits 236 */ updateClusterResource(Resource clusterResource, ResourceLimits resourceLimits)237 public void updateClusterResource(Resource clusterResource, 238 ResourceLimits resourceLimits); 239 240 /** 241 * Get the {@link ActiveUsersManager} for the queue. 242 * @return the <code>ActiveUsersManager</code> for the queue 243 */ getActiveUsersManager()244 public ActiveUsersManager getActiveUsersManager(); 245 246 /** 247 * Adds all applications in the queue and its subqueues to the given collection. 248 * @param apps the collection to add the applications to 249 */ collectSchedulerApplications(Collection<ApplicationAttemptId> apps)250 public void collectSchedulerApplications(Collection<ApplicationAttemptId> apps); 251 252 /** 253 * Detach a container from this queue 254 * @param clusterResource the current cluster resource 255 * @param application application to which the container was assigned 256 * @param container the container to detach 257 */ detachContainer(Resource clusterResource, FiCaSchedulerApp application, RMContainer container)258 public void detachContainer(Resource clusterResource, 259 FiCaSchedulerApp application, RMContainer container); 260 261 /** 262 * Attach a container to this queue 263 * @param clusterResource the current cluster resource 264 * @param application application to which the container was assigned 265 * @param container the container to attach 266 */ attachContainer(Resource clusterResource, FiCaSchedulerApp application, RMContainer container)267 public void attachContainer(Resource clusterResource, 268 FiCaSchedulerApp application, RMContainer container); 269 270 /** 271 * Check whether <em>disable_preemption</em> property is set for this queue 272 * @return true if <em>disable_preemption</em> is set, false if not 273 */ getPreemptionDisabled()274 public boolean getPreemptionDisabled(); 275 276 /** 277 * Get QueueCapacities of this queue 278 * @return queueCapacities 279 */ getQueueCapacities()280 public QueueCapacities getQueueCapacities(); 281 282 /** 283 * Get ResourceUsage of this queue 284 * @return resourceUsage 285 */ getQueueResourceUsage()286 public ResourceUsage getQueueResourceUsage(); 287 } 288