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  /** Returns A new checker for evaluating a batch rows. */
071  Checker newChecker();
072
073  /**
074   * Increment the counter if we build a valid task.
075   * @param regions The destination of task
076   * @param sn      The target server
077   */
078  void incTaskCounters(Collection<byte[]> regions, ServerName sn);
079
080  /**
081   * Decrement the counter if a task is accomplished.
082   * @param regions The destination of task
083   * @param sn      The target server
084   */
085  void decTaskCounters(Collection<byte[]> regions, ServerName sn);
086
087  /** Returns The number of running task. */
088  long getNumberOfTasksInProgress();
089
090  /**
091   * Waits for the running tasks to complete. If there are specified threshold and trigger, the
092   * implementation should wake up once in a while for checking the threshold and calling trigger.
093   * @param max             This method will return if the number of running tasks is less than or
094   *                        equal to max.
095   * @param id              the caller's id
096   * @param periodToTrigger The period to invoke the trigger. This value is a hint. The real period
097   *                        depends on the implementation.
098   * @param trigger         The object to call periodically.
099   * @throws java.io.InterruptedIOException If the waiting is interrupted
100   */
101  void waitForMaximumCurrentTasks(long max, long id, int periodToTrigger, Consumer<Long> trigger)
102    throws InterruptedIOException;
103
104  /**
105   * Wait until there is at least one slot for a new task.
106   * @param id              the caller's id
107   * @param periodToTrigger The period to invoke the trigger. This value is a hint. The real period
108   *                        depends on the implementation.
109   * @param trigger         The object to call periodically.
110   * @throws java.io.InterruptedIOException If the waiting is interrupted
111   */
112  void waitForFreeSlot(long id, int periodToTrigger, Consumer<Long> trigger)
113    throws InterruptedIOException;
114}