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.hbase.procedure2;
020
021import java.util.Iterator;
022import java.util.List;
023import java.util.concurrent.TimeUnit;
024import org.apache.yetus.audience.InterfaceAudience;
025
026import org.apache.hbase.thirdparty.com.google.common.annotations.VisibleForTesting;
027
028/**
029 * Keep track of the runnable procedures
030 */
031@InterfaceAudience.Private
032public interface ProcedureScheduler {
033  /**
034   * Start the scheduler
035   */
036  void start();
037
038  /**
039   * Stop the scheduler
040   */
041  void stop();
042
043  /**
044   * In case the class is blocking on poll() waiting for items to be added,
045   * this method should awake poll() and poll() should return.
046   */
047  void signalAll();
048
049  /**
050   * Inserts the specified element at the front of this queue.
051   * @param proc the Procedure to add
052   */
053  void addFront(Procedure proc);
054
055  /**
056   * Inserts the specified element at the front of this queue.
057   * @param proc the Procedure to add
058   * @param notify whether need to notify worker
059   */
060  void addFront(Procedure proc, boolean notify);
061
062  /**
063   * Inserts all elements in the iterator at the front of this queue.
064   */
065  void addFront(Iterator<Procedure> procedureIterator);
066
067  /**
068   * Inserts the specified element at the end of this queue.
069   * @param proc the Procedure to add
070   */
071  void addBack(Procedure proc);
072
073  /**
074   * Inserts the specified element at the end of this queue.
075   * @param proc the Procedure to add
076   * @param notify whether need to notify worker
077   */
078  void addBack(Procedure proc, boolean notify);
079
080  /**
081   * The procedure can't run at the moment.
082   * add it back to the queue, giving priority to someone else.
083   * @param proc the Procedure to add back to the list
084   */
085  void yield(Procedure proc);
086
087  /**
088   * The procedure in execution completed.
089   * This can be implemented to perform cleanups.
090   * @param proc the Procedure that completed the execution.
091   */
092  void completionCleanup(Procedure proc);
093
094  /**
095   * @return true if there are procedures available to process, otherwise false.
096   */
097  boolean hasRunnables();
098
099  /**
100   * Fetch one Procedure from the queue
101   * @return the Procedure to execute, or null if nothing present.
102   */
103  Procedure poll();
104
105  /**
106   * Fetch one Procedure from the queue
107   * @param onlyUrgent Only poll the urgent procedure to execute
108   * @return a Procedure
109   */
110  Procedure poll(boolean onlyUrgent);
111
112  /**
113   * Fetch one Procedure from the queue
114   * @param timeout how long to wait before giving up, in units of unit
115   * @param unit a TimeUnit determining how to interpret the timeout parameter
116   * @return the Procedure to execute, or null if nothing present.
117   */
118  Procedure poll(long timeout, TimeUnit unit);
119
120  /**
121   * Fetch one Procedure from the queue
122   * @param onlyUrgent Only poll the urgent procedure to execute
123   * @param timeout how long to wait before giving up, in units of unit
124   * @param unit a TimeUnit determining how to interpret the timeout parameter
125   * @return a Procedure
126   */
127  Procedure poll(boolean onlyUrgent, long timeout, TimeUnit unit);
128
129
130  /**
131   * List lock queues.
132   * @return the locks
133   */
134  List<LockedResource> getLocks();
135
136  /**
137   * @return {@link LockedResource} for resource of specified type & name. null if resource is not locked.
138   */
139  LockedResource getLockResource(LockedResourceType resourceType, String resourceName);
140
141  /**
142   * Returns the number of elements in this queue.
143   * @return the number of elements in this queue.
144   */
145  @VisibleForTesting
146  int size();
147
148  /**
149   * Clear current state of scheduler such that it is equivalent to newly created scheduler.
150   * Used for testing failure and recovery. To emulate server crash/restart,
151   * {@link ProcedureExecutor} resets its own state and calls clear() on scheduler.
152   */
153  @VisibleForTesting
154  void clear();
155}