nl.grons.sentries

core

package core

Visibility

Public
All

Type Members

class AdaptiveThroughputSentry extends ChainableSentry

A sentry that adapts throughput with the success ratio of invoking the protected resource.
A sentry that adapts throughput with the success ratio of invoking the protected resource. Think of it as a gradual circuit breaker.
The goal of this sentry is to protect the caller from a resource that slows down, or starts to produce errors when overloaded. By reducing throughput until success ratio is at an expected level, the resource can recover and work at its optimal efficiency.
For resources that behave correct most of the time, the target success ratio can be set quite high, e.g. 0.95. When exceptions are more 'normal', you may have to lower this parameter.
The success ratio is calculated per evaluationDelay with a simple 1 - (fail count / success count). When the success ratio is below targetSuccessRatio, the throughput is reduced to currentSuccessRatio * currentThroughputRatio. When the success ratio is again equal to or above the target ratio, throughput is increased by successIncreaseFactor (defaults to +20%) with a minimum of 0.0001D (1 in thousand calls may proceed). Note that regardless of the currentThroughputRatio, at least 1 call per evaluation period is allowed to continue.
This sentry only makes sense for high volume resources. To prevent throttling in low volume times, it is possible to set the minimum number of invocations that must be observed per evaluationDelay before throttling takes place. (see the minimumInvocationCountThreshold parameter).
It does not make sense to throttle on fast failing invocations. In those cases its better to get the exception from the underlying resource then to get a ReducedThroughputException. Parameter failedInvocationDurationThreshold sets the minimum duration of failed invocation in order for those invocations to be counted as failed. By setting this value to a non-zero value, fast failures do not reduce throughput. (Note that the default is 0 for backward compatibility.)
When there is a calamity, this sentry only reacts as fast as the given evaluationDelay (1 second by default). When the resource becomes fully available, it takes at most 39 evaluation before throughput is back at 100%. You can test this by evaluating the following code in a Scala REPL:
```
scala> val successIncreaseFactor = 1.2D
successIncreaseFactor: Double = 1.2

scala> Stream.iterate(0.0D)(x => (x * successIncreaseFactor).max(0.001).min(1.0D)).zipWithIndex.takeWhile(_._1 < 1.0).last._2 + 1
res0 Int = 39
```
A new instance can be obtained through the nl.grons.sentries.SentrySupport mixin.
class CircuitBreakerBrokenException extends NotAvailableException

Circuit breaker is in broken state, invocations are failing immediately.
class CircuitBreakerSentry extends ChainableSentry

A sentry that limits the number of consecutive failures; a.k.a.
A sentry that limits the number of consecutive failures; a.k.a. a circuit breaker. A new instance can be obtained through the nl.grons.sentries.SentrySupport mixin.
The goal of a circuit breaker is to protect the caller from a resource that fails. It also protects the resource from overload when it is trying to recover. A circuit breaker works by keeping track of the number of consecutive failures. When there are more then consecutive failLimit failures, the circuit breaker 'breaks' and pro-actively blocks all following calls by throwing a nl.grons.sentries.core.CircuitBreakerBrokenException.
Every retryDelay one invocation is allowed through in order to test the resource. When this call succeeds, the circuit breaker goes back to the flow state. If not, it stays in the broken state.
Please see http://day-to-day-stuff.blogspot.com/2013/02/breaking-circuit-breaker.html for a rationale of the used vocabulary (broken/flow state vs. the more known open/half open/close state).
class ConcurrencyLimitExceededException extends NotAvailableException

Concurrency limit exceeded, invocations are failing immediately.
class ConcurrencyLimitSentry extends ChainableSentry

A sentry that limits the number of concurrent invocations.
A sentry that limits the number of concurrent invocations. A new instance can be obtained through the nl.grons.sentries.SentrySupport mixin.
The goal of a concurrency limiter is to prevent overloading of a shared resource. This sentry can be used as an alternative to a pool for easy to crate objects.
class DurationLimitExceededException extends NotAvailableException

Duration limit of an invocation was exceeded.
class DurationLimitSentry extends ChainableSentry

A sentry that limits the duration of an invocation.
A sentry that limits the duration of an invocation. A new instance can be obtained through the nl.grons.sentries.SentrySupport mixin.
The goal of a duration limiter is to support callers that are only interested in the results for a limited time.
WARNING: do NOT use this sentry when you invoke it from a Future or an Actor. For such circumstances you are MUCH better of with a timeout on the enclosing future or a timeout message within the actor. Reason: this sentry blocks the current thread while waiting on a future that executes the task. Blocking the current thread is an anti-pattern for futures and actors.
Note that when the wait period has passed, the task still completes in another thread. Make sure there are enough threads in the executor. By default a Executors.newCachedThreadPool() is used which creates as much threads as needed. The executor can be changed by overriding .executionContext.
abstract class LoadBalancer[R] extends AnyRef

Does load balancing between several resources.
Does load balancing between several resources.
Warning: the API is definitely not yet stable. When used wrong, you cause a memory leak. Use at your own risk.
R
type of resource
class MetricSentry extends ChainableSentry

Sentry that collects metric of invocations.
Sentry that collects metric of invocations. A new instance can be obtained through the nl.grons.sentries.SentrySupport mixin.
The following metrics are created:
- timer "all" for all invocations - meter "notAvailable" for invocations leading to a nl.grons.sentries.support.NotAvailableException, e.g. all invocations blocked by a sentry - meter "fail" for other failed invocations
Note that in other to make effective use of the "notAvailable" meter, this sentry must be the first sentry in the chain.
This sentry can not be used in the same sentry chain as the nl.grons.sentries.core.TimerSentry.
class NoResourcesAvailableException extends NotAvailableException

No resources present at all, invocations are failing immediately.
class RateLimitExceededException extends NotAvailableException

Rate limit exceeded, invocations are failing immediately.
class RateLimitSentry extends ChainableSentry

A sentry that limits the number of invocations per time span.
A sentry that limits the number of invocations per time span. A new instance can be obtained through the nl.grons.sentries.SentrySupport mixin.
A rate limiter is useful for cases where you asynchronously hand of some work and you don't want to overload the receiver. For example sending error emails or an asynchronous rendering job for which there is a limited capacity. For other cases a nl.grons.sentries.core.ConcurrencyLimitSentry is usually more appropriate.
class ReducedThroughputException extends NotAvailableException

Access to resource was blocked temporarily because throughput is currently reduced.
class TimerSentry extends ChainableSentry

Sentry that times invocations.
Sentry that times invocations. A new instance can be obtained through the nl.grons.sentries.SentrySupport mixin.
A single metrics is created: timer "all" for all invocations.
This sentry can not be used in the same sentry chain as the nl.grons.sentries.core.MetricSentry.

Value Members

object DurationLimitSentry

Ungrouped