Interface CapacityLimiter


public interface CapacityLimiter
A provider of capacity for a client or server.

Capacity Capacity for an entity is defined as the number of concurrent requests that it can process without significantly affecting resource consumption or likelihood to successfully process in a timely manner given currently available resources vs resources required to process the new request. This capacity offered can be static or dynamic and the semantics of determination is left to implementations.

Consumption As the capacity is defined in terms of concurrent requests, as new requests are seen, some portion of this capacity is deemed to be consumed till a subsequent callback marks the end of processing for that request. Number of times that tryAcquire(Classification, ContextMap) is called without a corresponding termination callback is termed as demand.

Request Lifetime Request processing starts when tryAcquire(Classification, ContextMap) is called and returns a non-null CapacityLimiter.Ticket and terminates when either one of the following occurs:

Request Classifications Requests can be classified with different classes, that can be taken into consideration when a CapacityLimiter implementation supports this. Classification is used as hint from the user of the importance of the incoming request, and are not guaranteed to have an influence to the decision if the CapacityLimiter doesn't support them or chooses to ignore them.

  • Method Details

    • name

      String name()
      Identifying name for this CapacityLimiter.
      Returns:
      the name of this CapacityLimiter.
    • tryAcquire

      @Nullable CapacityLimiter.Ticket tryAcquire(Classification classification, @Nullable ContextMap context)
      Evaluate whether there is enough capacity to allow the call for the given Classification and the context.
      Parameters:
      classification - A class tha represents the importance of a request, to be evaluated upon permit.
      context - Contextual metadata supported for evaluation from the call-site. This, in an HTTP context would typically be the HttpRequest#context().
      Returns:
      CapacityLimiter.Ticket when capacity is enough to satisfy the demand or null when not.
      See Also: