@InterfaceAudience.Public
@InterfaceStability.Evolving
public final class PleaseThrottleException
extends KuduException
implements HasFailedRpcException

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

Since all APIs of AsyncKuduSession are asynchronous and non-blocking, it's possible that the application would produce RPCs at a rate higher than Kudu is able to handle. When this happens, AsyncKuduSession 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.

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 Kudu. 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 this exception, so they don't need complex throttling logic.