ratpack.exec.Throttle Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of ratpack-core Show documentation

The core HTTP and composition mechanisms of Ratpack

There is a newer version: 2.0.0-rc-1

/*
 * Copyright 2014 the original author or authors.
 *
 * Licensed 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 ratpack.exec;

import ratpack.exec.internal.DefaultThrottle;
import ratpack.exec.internal.UnlimitedThrottle;

/**
 * Limits the concurrency of operations, typically access to an external resource.
 * 
 * A given throttle limits the amount of concurrently executing promise, effectively limiting concurrency.
 * 

 * The queueing employed by the throttle is generally fair (i.e. oldest promises execute first), but this is not completely guaranteed.
 *
 * @see Promise#throttled(Throttle)
 */
public interface Throttle {

  /**
   * Create a new throttle of the given size.
   *
   * @param size the desired size
   * @return a new throttle of the given size
   */
  static Throttle ofSize(int size) {
    return new DefaultThrottle(size);
  }

  /**
   * Create a new throttle that does not limit concurrency.
   *
   * @return an unlimited throttle
   */
  static Throttle unlimited() {
    return new UnlimitedThrottle();
  }

  /**
   * Throttles the given promise.
   *
   * @param promise the promise to throttle
   * @param  the type of promised value
   * @return the throttled promise
   */
   Promise throttle(Promise promise);

  /**
   * The size of this throttle.
   * 

   * The throttle guarantees that no more than this number of promises that were throttled via {@link #throttle(Promise)} will execute at the same time.
   * 
   * Returns < 1 if the throttle is unlimited.
   *
   * @return the throttle size
   */
  int getSize();

  /**
   * How many throttled promises are currently executing.
   *
   * @return how many throttled promises are currently executing
   */
  int getActive();

  /**
   * The number of throttled promises that are waiting to execute (that is, the queue size).
   *
   * @return the number of promises waiting to execute
   */
  int getWaiting();
}