org.hbase.async
Class PleaseThrottleException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          java.lang.RuntimeException
              org.hbase.async.HBaseException
                  org.hbase.async.NonRecoverableException
                      org.hbase.async.PleaseThrottleException

All Implemented Interfaces:

Serializable, HasFailedRpcException

public final class PleaseThrottleException
extends NonRecoverableException
implements HasFailedRpcException

This exception notifies the application to throttle its use of HBase.

Since all APIs of HBaseClient are asynchronous and non-blocking, it's possible that the application would produce RPCs at a rate higher than HBase is able to handle. When this happens, HBaseClient will typically do some buffering up to a certain point beyond which RPCs will fail-fast with this exception, to prevent the application from running itself out of memory.

This exception is expected to be handled by having the application throttle or pause itself for a short period of time before retrying the RPC that failed with this exception as well as before sending other RPCs. The reason this exception inherits from NonRecoverableException instead of RecoverableException is that the usual course of action when handling a RecoverableException is to retry right away, which would defeat the whole purpose of this exception. Here, we want the application to retry after a reasonable delay as well as throttle the pace of creation of new RPCs. What constitutes a "reasonable delay" depends on the nature of RPCs and rate at which they're produced. For a write-heavy high-throughput application, this exception will typically be used when HBase is in the process of splitting a region or migrating a region to another server, in which case the application should stop producing new writes for typically at least 1 second (or significantly slow down its pace, to let HBaseClient buffer the writes).

When HBaseClient buffers RPCs, it typically uses this exception with a low watermark and a high watermark. When the buffer hits the low watermark, the next (unlucky) RPC that wants to be buffered will be failed with a PleaseThrottleException, to send an "advisory warning" to the application that it needs to throttle itself. All subsequent RPCs that need to be buffered will be buffered until the buffer hits the high watermark. Once the high watermark has been hit, all subsequent RPCs that need to be buffered will fail-fast with a PleaseThrottleException.

One effective strategy to handle this exception is to set a flag to true when this exception is first emitted that causes the application to pause or throttle its use of HBase. Then you can retry the RPC that failed (which is accessible through getFailedRpc()) and add a callback to it in order to unset the flag once the RPC completes successfully. Note that low-throughput applications will typically rarely (if ever) hit the low watermark and should never hit the high watermark, so they don't need complex throttling logic.

See Also:

Serialized Form

Method Summary

Deferred	getDeferred() Returns a deferred one can wait on before retrying the failed RPC.
HBaseRpc	getFailedRpc() The RPC that was made to fail with this exception.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getFailedRpc

public HBaseRpc getFailedRpc()

The RPC that was made to fail with this exception.

Specified by:

getFailedRpc in interface HasFailedRpcException

getDeferred

public Deferred getDeferred()

Returns a deferred one can wait on before retrying the failed RPC.

Since:

1.3