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 */
018package org.apache.hadoop.hbase.client;
019
020import java.io.InterruptedIOException;
021import java.util.Collection;
022import java.util.function.Consumer;
023import org.apache.hadoop.hbase.HRegionLocation;
024import org.apache.hadoop.hbase.ServerName;
025import org.apache.yetus.audience.InterfaceAudience;
026
027/**
028 * An interface for client request scheduling algorithm.
029 */
030@InterfaceAudience.Public
031public interface RequestController {
032
033  @InterfaceAudience.Public
034  public enum ReturnCode {
035    /**
036     * Accept current row.
037     */
038    INCLUDE,
039    /**
040     * Skip current row.
041     */
042    SKIP,
043    /**
044     * No more row can be included.
045     */
046    END
047  }
048
049  /**
050   * Picks up the valid data.
051   */
052  @InterfaceAudience.Public
053  public interface Checker {
054    /**
055     * Checks the data whether it is valid to submit.
056     * @param loc the destination of data
057     * @param row the data to check
058     * @return describe the decision for the row
059     */
060    ReturnCode canTakeRow(HRegionLocation loc, Row row);
061
062    /**
063     * Reset the state of the scheduler when completing the iteration of rows.
064     * @throws InterruptedIOException some controller may wait for some busy region or RS to
065     *                                complete the undealt request.
066     */
067    void reset() throws InterruptedIOException;
068  }
069
070  /**
071   * @return A new checker for evaluating a batch rows.
072   */
073  Checker newChecker();
074
075  /**
076   * Increment the counter if we build a valid task.
077   * @param regions The destination of task
078   * @param sn      The target server
079   */
080  void incTaskCounters(Collection<byte[]> regions, ServerName sn);
081
082  /**
083   * Decrement the counter if a task is accomplished.
084   * @param regions The destination of task
085   * @param sn      The target server
086   */
087  void decTaskCounters(Collection<byte[]> regions, ServerName sn);
088
089  /**
090   * @return The number of running task.
091   */
092  long getNumberOfTasksInProgress();
093
094  /**
095   * Waits for the running tasks to complete. If there are specified threshold and trigger, the
096   * implementation should wake up once in a while for checking the threshold and calling trigger.
097   * @param max             This method will return if the number of running tasks is less than or
098   *                        equal to max.
099   * @param id              the caller's id
100   * @param periodToTrigger The period to invoke the trigger. This value is a hint. The real period
101   *                        depends on the implementation.
102   * @param trigger         The object to call periodically.
103   * @throws java.io.InterruptedIOException If the waiting is interrupted
104   */
105  void waitForMaximumCurrentTasks(long max, long id, int periodToTrigger, Consumer<Long> trigger)
106    throws InterruptedIOException;
107
108  /**
109   * Wait until there is at least one slot for a new task.
110   * @param id              the caller's id
111   * @param periodToTrigger The period to invoke the trigger. This value is a hint. The real period
112   *                        depends on the implementation.
113   * @param trigger         The object to call periodically.
114   * @throws java.io.InterruptedIOException If the waiting is interrupted
115   */
116  void waitForFreeSlot(long id, int periodToTrigger, Consumer<Long> trigger)
117    throws InterruptedIOException;
118}