Statefulness of policies

ℹ️ This documentation describes the previous Polly v7 API. If you are using the new v8 API, please refer to pollydocs.org.

All Polly policy instances are thread-safe to use at multiple call sites and for concurrent calls.

Some Polly policies are stateful by nature of their intended function:

Policy type	Statefulness	Purpose
CircuitBreaker	Stateful across calls	To track call success/failure rates, to govern the circuit
Bulkhead	Stateful across calls	To track bulkhead usage against capacity
Cache	Stateful across calls	To cache items in the underlying cache as requested
All other policy types	Stateless across calls	-

This has intended functional consequences when you re-use an instance of these types of Policy across call sites.

CircuitBreaker

CircuitBreaker's purpose to count and act according to success/fail metrics across calls placed through the policy. It stores those counts in internal state. The intended functional consequence is that if you share a CircuitBreakerPolicy instance in multiple call sites or executions, those call sites or executions will share circuit state.

• Share the same breaker policy instance across call sites when you want those call sites to break in common - for instance they have a common downstream dependency.
• Don't share a breaker instance across call sites when you want those call sites to have independent circuit state and break independently.

Bulkhead

Bulkhead's purpose is to limit concurrency of calls placed through it. Each single BulkheadPolicy instance tracks that concurrency in internal state. The intended functional consequence is that when you share a BulkheadPolicy instance across call-sites, those call-sites share the bulkhead capacity between them.

• Share the same BulkheadPolicy instance across multiple call sites when you want call sites to share the bulkhead capacity amongst them.
• Don't share the same BulkheadPolicy instance across multiple call sites when you want the call sites to have independent bulkhead capacity.

Cache

The underlying cache provider supporting a CachePolicy is evidently stateful. A single CachePolicy instance however is safely reusable across call sites for caching multiple different keys. Context.OperationKey, scoped to the execution, supplies the key to cache under and so isolates usage at different call sites.