Interface CapacityLimiter
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:
- When the request is successfully completed (Default:
CapacityLimiter.Ticket.completed()
) - When the request fails due to an external capacity rejection i.e., dropped (Default:
CapacityLimiter.Ticket.dropped()
) - When the request fails due to a local error (Default:
CapacityLimiter.Ticket.failed(Throwable)
) - When the request is cancelled (Default:
CapacityLimiter.Ticket.ignored()
)
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.
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interface
Representation of the state of theCapacityLimiter
when theCapacityLimiter.Ticket
is issued.static interface
Result oftryAcquire(Classification, ContextMap)
when capacity is enough to meet the demand. -
Method Summary
Modifier and TypeMethodDescriptionname()
Identifying name for thisCapacityLimiter
.tryAcquire
(Classification classification, ContextMap context) Evaluate whether there is enough capacity to allow the call for the givenClassification
and thecontext
.
-
Method Details
-
name
String name()Identifying name for thisCapacityLimiter
.- 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 givenClassification
and thecontext
.- 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 theHttpRequest#context()
.- Returns:
CapacityLimiter.Ticket
when capacity is enough to satisfy the demand ornull
when not.- See Also:
-