com.twitter.common.util
Class BackoffDecider

java.lang.Object
  extended by com.twitter.common.util.BackoffDecider

public class BackoffDecider
extends Object

Handles logic for deciding whether to back off from calls to a backend. This works by offering a guard method shouldBackOff(), which instructs the caller whether they should avoid making the call. The backoff logic will maintain statistics about the failure rate, and push into a backoff state (silent period) when the failure rate exceeds the configured threshold. At the end of the quiet period, a recovery state will be entered, during which the decider will allow traffic to ramp back up to full capacity. The expected use case looks something like this:

 void sendRequestGuarded() {
   if (!decider.shouldBackOff()) {
     boolean success = sendRequestUnguarded();
     if (success) {
       decider.addSuccess();
     } else {
       decider.addFailure();
     }
   }
 }
 


Nested Class Summary
static class BackoffDecider.Builder
          Builder class to configure a BackoffDecider.
static class BackoffDecider.RecoveryType
          Different types of recovery mechanisms to use after exiting the backoff state.
 
Method Summary
 void addFailure()
          Records a failed request to the backend.
 void addSuccess()
          Records a successful request to the backend.
 long awaitBackoff()
          Checks whether the caller should back off and if not then returns immediately; otherwise the method blocks until it is safe for the caller to proceed without backing off further based on all data available at the time of this call.
static BackoffDecider.Builder builder(String name)
          Creates a builder object.
 boolean shouldBackOff()
          Checks whether this decider instructs the caller that it should back off from the associated backend.
 void transitionToBackOff(double failRate, boolean force)
          Transitions the state to BACKOFF and logs a message appropriately if it is doing so because of high fail rate or by force.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

awaitBackoff

public long awaitBackoff()
                  throws InterruptedException
Checks whether the caller should back off and if not then returns immediately; otherwise the method blocks until it is safe for the caller to proceed without backing off further based on all data available at the time of this call.

Returns:
the amount of time in nanoseconds spent awaiting backoff
Throws:
InterruptedException - if the calling thread was interrupted while backing off

shouldBackOff

public boolean shouldBackOff()
Checks whether this decider instructs the caller that it should back off from the associated backend. This is determined based on the response history for the backend as well as the backoff state of the decider group (if configured).

Returns:
true if the decider is in backoff mode, otherwise false.

addFailure

public void addFailure()
Records a failed request to the backend.


addSuccess

public void addSuccess()
Records a successful request to the backend.


transitionToBackOff

public void transitionToBackOff(double failRate,
                                boolean force)
Transitions the state to BACKOFF and logs a message appropriately if it is doing so because of high fail rate or by force.

Parameters:
failRate - rate of request failures on this host.
force - if true, forces the transition to BACKOFF. Typically used in cases when the host was not found to be alive by LiveHostChecker.

builder

public static BackoffDecider.Builder builder(String name)
Creates a builder object.

Parameters:
name - Name for the backoff decider to build.
Returns:
A builder.