Polly and interfaces

Polly and interfaces

TL/DR

Policy v5.2.0 introduces interfaces.

Polly's interfaces are intended to support PolicyRegistry and to group Policy functionality by the interface segregation principle. Polly's interfaces are not intended for coding your own policy implementations against.

Execution interfaces and policy-type interfaces

There are two kinds of interface:

• Execution interfaces define the executions which can be made through a policy via the Execute(...) (and similar) overloads
• Policy-type interfaces bring together common properties of all policies of a given type (for example, circuitbreaker policies)

The execution interfaces

The execution interfaces are ISyncPolicy, ISyncPolicy<TResult>, IAsyncPolicy and IAsyncPolicy<TResult>.

These interfaces define the executions which can be made through a policy via the Execute(...), ExecuteAndCapture(...) overloads and their async equivalents.

Interface	Usage
ISyncPolicy	for synchronous executions returning void; and for delegates returning any TResult, when HandleResult<TResult>(...) and FallbackPolicy<TResult> are not used.
ISyncPolicy<TResult>	for synchronous executions of delegates returning TResult
IAsyncPolicy	for asynchronous executions returning void; and for delegates returning any TResult, when HandleResult<TResult>(...) and FallbackPolicy<TResult> are not used.
IAsyncPolicy<TResult>	for asynchronous executions of delegates returning TResult

Recent blog posts outline why Polly has both non-generic and generic policies and separate sync and async policies.

The Policy-type interfaces

A second, orthogonal set of interfaces denotes the policy type (eg ICircuitBreakerPolicy). The full set of policy-type interfaces is:

• IBulkheadPolicy
• ICircuitBreakerPolicy
• IFallbackPolicy
• INoOpPolicy
• IRetryPolicy
• ITimeoutPolicy
• IPolicyWrap

Generic variants

Each also exists in a generic form such as ICircuitBreakerPolicy<TResult>.

Policy-type interfaces expose features specific to that policy type

Where a policy exposes public methods and properties about its state, these are defined on the given interface. For instance, ICircuitBreakerPolicy<TResult> defines:

• CircuitState CircuitState
• Exception LastException
• void Isolate()
• void Reset()

and ICircuitBreakerPolicy<TResult> adds:

• TResult LastHandledResult.

This can be used, for instance, to establish custom monitoring of the state of all your circuit-breakers across your application (regardless of whether those circuit-breaker policy instances were for sync or async calls, generic or non-generic).

IsPolicy interface

The IsPolicy interface is an empty marker interface simply denoting that the item is a Polly policy of some kind. It is used by PolicyRegistry to hold all kinds of Policy.

Implementing your own policies

It is not intended that the interfaces are used to implement new, custom policies. Fulfilling all the overloads of (for example) ISyncPolicy would be a cumbersome approach; and this is already covered by the abstract base class Policy. Custom policies should be implemented by extending the abstract Policy and Policy<TResult> base classes (to be covered in a future article).