/**
    * 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.hbase.quotas;
  
  import java.util.concurrent.TimeUnit;
  
  import org.apache.hadoop.hbase.classification.InterfaceAudience;
  import org.apache.hadoop.hbase.classification.InterfaceStability;
  
  import com.google.common.annotations.VisibleForTesting;
  
  /**
   * Simple rate limiter.
   *
   * Usage Example:
   *    // At this point you have a unlimited resource limiter
   *   RateLimiter limiter = new AverageIntervalRateLimiter();
   *                         or new FixedIntervalRateLimiter();
   *   limiter.set(10, TimeUnit.SECONDS);       // set 10 resources/sec
   *
   *   while (true) {
   *     // call canExecute before performing resource consuming operation
   *     bool canExecute = limiter.canExecute();
   *     // If there are no available resources, wait until one is available
   *     if (!canExecute) Thread.sleep(limiter.waitInterval());
   *     // ...execute the work and consume the resource...
   *     limiter.consume();
   *   }
   */
  @InterfaceAudience.Private
  @InterfaceStability.Evolving
  @edu.umd.cs.findbugs.annotations.SuppressWarnings(value="IS2_INCONSISTENT_SYNC",
    justification="FindBugs seems confused; says limit and tlimit " +
    "are mostly synchronized...but to me it looks like they are totally synchronized")
  public abstract class RateLimiter {
    public static final String QUOTA_RATE_LIMITER_CONF_KEY = "hbase.quota.rate.limiter";
    private long tunit = 1000;           // Timeunit factor for translating to ms.
    private long limit = Long.MAX_VALUE; // The max value available resource units can be refilled to.
    private long avail = Long.MAX_VALUE; // Currently available resource units
  
    /**
     * Refill the available units w.r.t the elapsed time.
     * @param limit Maximum available resource units that can be refilled to.
     * @return how many resource units may be refilled ?
     */
    abstract long refill(long limit);
  
    /**
     * Time in milliseconds to wait for before requesting to consume 'amount' resource.
     * @param limit Maximum available resource units that can be refilled to.
     * @param available Currently available resource units
     * @param amount Resources for which time interval to calculate for
     * @return estimate of the ms required to wait before being able to provide 'amount' resources.
     */
    abstract long getWaitInterval(long limit, long available, long amount);
  
  
    /**
     * Set the RateLimiter max available resources and refill period.
     * @param limit The max value available resource units can be refilled to.
     * @param timeUnit Timeunit factor for translating to ms.
     */
    public synchronized void set(final long limit, final TimeUnit timeUnit) {
      switch (timeUnit) {
      case MILLISECONDS:
        tunit = 1;
        break;
      case SECONDS:
        tunit = 1000;
        break;
      case MINUTES:
        tunit = 60 * 1000;
        break;
      case HOURS:
        tunit = 60 * 60 * 1000;
        break;
      case DAYS:
        tunit = 24 * 60 * 60 * 1000;
        break;
      default:
        throw new RuntimeException("Unsupported " + timeUnit.name() + " TimeUnit.");
      }
      this.limit = limit;
      this.avail = limit;
    }
  
    public String toString() {
      String rateLimiter = this.getClass().getSimpleName();
      if (getLimit() == Long.MAX_VALUE) {
        return rateLimiter + "(Bypass)";
     }
     return rateLimiter + "(avail=" + getAvailable() + " limit=" + getLimit() +
         " tunit=" + getTimeUnitInMillis() + ")";
   }
 
   /**
    * Sets the current instance of RateLimiter to a new values.
    *
    * if current limit is smaller than the new limit, bump up the available resources.
    * Otherwise allow clients to use up the previously available resources.
    */
   public synchronized void update(final RateLimiter other) {
     this.tunit = other.tunit;
     if (this.limit < other.limit) {
       // If avail is capped to this.limit, it will never overflow,
       // otherwise, avail may overflow, just be careful here.
       long diff = other.limit - this.limit;
       if (this.avail <= Long.MAX_VALUE - diff) {
         this.avail += diff;
         this.avail = Math.min(this.avail, other.limit);
       } else {
         this.avail = other.limit;
       }
     }
     this.limit = other.limit;
   }
 
   public synchronized boolean isBypass() {
     return getLimit() == Long.MAX_VALUE;
   }
 
   public synchronized long getLimit() {
     return limit;
   }
 
   public synchronized long getAvailable() {
     return avail;
   }
 
   protected synchronized long getTimeUnitInMillis() {
     return tunit;
   }
 
   /**
    * Is there at least one resource available to allow execution?
    * @return true if there is at least one resource available, otherwise false
    */
   public boolean canExecute() {
     return canExecute(1);
   }
 
   /**
    * Are there enough available resources to allow execution?
    * @param amount the number of required resources, a non-negative number
    * @return true if there are enough available resources, otherwise false
    */
   public synchronized boolean canExecute(final long amount) {
     if (isBypass()) {
       return true;
     }
 
     long refillAmount = refill(limit);
     if (refillAmount == 0 && avail < amount) {
       return false;
     }
     // check for positive overflow
     if (avail <= Long.MAX_VALUE - refillAmount) {
       avail = Math.max(0, Math.min(avail + refillAmount, limit));
     } else {
       avail = Math.max(0, limit);
     }
     if (avail >= amount) {
       return true;
     }
     return false;
   }
 
   /**
    * consume one available unit.
    */
   public void consume() {
     consume(1);
   }
 
   /**
    * consume amount available units, amount could be a negative number
    * @param amount the number of units to consume
    */
   public synchronized void consume(final long amount) {
 
     if (isBypass()) {
       return;
     }
 
     if (amount >= 0 ) {
       this.avail -= amount;
       if (this.avail < 0) {
         this.avail = 0;
       }
     } else {
       if (this.avail <= Long.MAX_VALUE + amount) {
         this.avail -= amount;
         this.avail = Math.min(this.avail, this.limit);
       } else {
         this.avail = this.limit;
       }
     }
   }
 
   /**
    * @return estimate of the ms required to wait before being able to provide 1 resource.
    */
   public long waitInterval() {
     return waitInterval(1);
   }
 
   /**
    * @return estimate of the ms required to wait before being able to provide "amount" resources.
    */
   public synchronized long waitInterval(final long amount) {
     // TODO Handle over quota?
     return (amount <= avail) ? 0 : getWaitInterval(getLimit(), avail, amount);
   }
 
   // These two method are for strictly testing purpose only
   @VisibleForTesting
   public abstract void setNextRefillTime(long nextRefillTime);
 
   @VisibleForTesting
   public abstract long getNextRefillTime();
 }