/*******************************************************************************
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*******************************************************************************/
package org.apache.hadoop.yarn.server.resourcemanager.reservation;
import java.util.Collection;
import org.apache.hadoop.yarn.server.resourcemanager.scheduler.ResourceScheduler;
import org.apache.hadoop.yarn.util.Clock;
/**
* A PlanFollower is a component that runs on a timer, and synchronizes the
* underlying {@link ResourceScheduler} with the {@link Plan}(s) and viceversa.
*
* While different implementations might operate differently, the key idea is to
* map the current allocation of resources for each active reservation in the
* plan(s), to a corresponding notion in the underlying scheduler (e.g., tuning
* capacity of queues, set pool weights, or tweak application priorities). The
* goal is to affect the dynamic allocation of resources done by the scheduler
* so that the jobs obtain access to resources in a way that is consistent with
* the reservations in the plan. A key conceptual step here is to convert the
* absolute-valued promises made in the reservations to appropriate relative
* priorities/queue sizes etc.
*
* Symmetrically the PlanFollower exposes changes in cluster conditions (as
* tracked by the scheduler) to the plan, e.g., the overall amount of physical
* resources available. The Plan in turn can react by replanning its allocations
* if appropriate.
*
* The implementation can assume that is run frequently enough to be able to
* observe and react to normal operational changes in cluster conditions on the
* fly (e.g., if cluster resources drop, we can update the relative weights of a
* queue so that the absolute promises made to the job at reservation time are
* respected).
*
* However, due to RM restarts and the related downtime, it is advisable for
* implementations to operate in a stateless way, and be able to synchronize the
* state of plans/scheduler regardless of how big is the time gap between
* executions.
*/
public interface PlanFollower extends Runnable {
/**
* Init function that configures the PlanFollower, by providing:
*
* @param clock a reference to the system clock.
* @param sched a reference to the underlying scheduler
* @param plans references to the plans we should keep synchronized at every
* time tick.
*/
public void init(Clock clock, ResourceScheduler sched, Collection<Plan> plans);
/**
* The function performing the actual synchronization operation for a given
* Plan. This is normally invoked by the run method, but it can be invoked
* synchronously to avoid race conditions when a user's reservation request
* start time is imminent.
*
* @param plan the Plan to synchronize
*/
public void synchronizePlan(Plan plan);
/**
* Setter for the list of plans.
*
* @param plans the collection of Plans we operate on at every time tick.
*/
public void setPlans(Collection<Plan> plans);
}