001/*
002 *
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *     http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing, software
014 * distributed under the License is distributed on an "AS IS" BASIS,
015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 */
019
020package org.apache.hadoop.hbase.client;
021
022import java.io.InterruptedIOException;
023import java.util.Collection;
024import java.util.function.Consumer;
025import org.apache.hadoop.hbase.HRegionLocation;
026import org.apache.hadoop.hbase.ServerName;
027import org.apache.yetus.audience.InterfaceAudience;
028
029/**
030 * An interface for client request scheduling algorithm.
031 */
032@InterfaceAudience.Public
033public interface RequestController {
034
035  @InterfaceAudience.Public
036  public enum ReturnCode {
037    /**
038     * Accept current row.
039     */
040    INCLUDE,
041    /**
042     * Skip current row.
043     */
044    SKIP,
045    /**
046     * No more row can be included.
047     */
048    END
049  }
050
051  /**
052   * Picks up the valid data.
053   */
054  @InterfaceAudience.Public
055  public interface Checker {
056    /**
057     * Checks the data whether it is valid to submit.
058     * @param loc the destination of data
059     * @param row the data to check
060     * @return describe the decision for the row
061     */
062    ReturnCode canTakeRow(HRegionLocation loc, Row row);
063
064    /**
065     * Reset the state of the scheduler when completing the iteration of rows.
066     * @throws InterruptedIOException some controller may wait
067     * for some busy region or RS to complete the undealt request.
068     */
069    void reset() throws InterruptedIOException ;
070  }
071
072  /**
073   * @return A new checker for evaluating a batch rows.
074   */
075  Checker newChecker();
076
077  /**
078   * Increment the counter if we build a valid task.
079   * @param regions The destination of task
080   * @param sn The target server
081   */
082  void incTaskCounters(Collection<byte[]> regions, ServerName sn);
083
084  /**
085   * Decrement the counter if a task is accomplished.
086   * @param regions The destination of task
087   * @param sn The target server
088   */
089  void decTaskCounters(Collection<byte[]> regions, ServerName sn);
090
091  /**
092   * @return The number of running task.
093   */
094  long getNumberOfTasksInProgress();
095
096  /**
097   * Waits for the running tasks to complete.
098   * If there are specified threshold and trigger, the implementation should
099   * wake up once in a while for checking the threshold and calling trigger.
100   * @param max This method will return if the number of running tasks is
101   * less than or equal to max.
102   * @param id the caller's id
103   * @param periodToTrigger The period to invoke the trigger. This value is a
104   * hint. The real period depends on the implementation.
105   * @param trigger The object to call periodically.
106   * @throws java.io.InterruptedIOException If the waiting is interrupted
107   */
108  void waitForMaximumCurrentTasks(long max, long id,
109    int periodToTrigger, Consumer<Long> trigger) throws InterruptedIOException;
110
111  /**
112   * Wait until there is at least one slot for a new task.
113   * @param id the caller's id
114   * @param periodToTrigger The period to invoke the trigger. This value is a
115   * hint. The real period depends on the implementation.
116   * @param trigger The object to call periodically.
117   * @throws java.io.InterruptedIOException If the waiting is interrupted
118   */
119  void waitForFreeSlot(long id, int periodToTrigger,
120          Consumer<Long> trigger) throws InterruptedIOException;
121}