asyncutils.altlocks¶

Non-conventional asynchronous synchronization primitives that may not adhere to the traditional lock interface.

Classes¶

`CircuitBreaker`
`DynamicThrottle`	Limit the rate of a function being called.
`Releasing`	Essentially invert the roles of the async enter and exit methods of a lock.
`ResourceGuard`	A sync- and async-compatible context manager, inspired by `anyio.ResourceGuard`, which causes contention of a shared resource to fail fast.
`StatefulBarrier`	An async barrier, that unlike traditional barriers, accumulates state from parties in a deque and makes it available once the barrier is tripped.
`UniqueResourceGuard`	A subclass of `ResourceGuard` that only allows one guard per object. Cannot be further subclassed.

Module Contents¶

class asyncutils.altlocks.CircuitBreaker[source]¶

The circuit breaker pattern. Use on async functions that may fail often, such as requests to an unreliable server.

Instances can be used as decorators, unless instantiated with a function as the first parameter, in which case the decorated function is returned.

Construct a circuit breaker, whose circuit is initially closed.
If name is passed, use it as its name; return a function wrapping f otherwise, deriving the name of the circuit breaker from the function. This derivation follows exactly one level of __wrapped__-based wrapping after retrieving the __func__ attribute if present.
Pass exceptions that are expected to happen through the exc parameter.
When the decorated function fails more than max_fails times (default CIRCUIT_BREAKER_DEFAULT_MAX_FAILS), the breaker triggers (opens the circuit, so to say) and disallows further calls of the wrapped functions by throwing an exception.
This state persists until the reset timeout expires (default CIRCUIT_BREAKER_DEFAULT_RESET). Then, the breaker enters the half-open state.
If the function completes successfully when the breaker is half-open under max_half_open_calls (default CIRCUIT_BREAKER_DEFAULT_MAX_HALF_OPEN_CALLS) tries, the circuit closes automatically. Otherwise, the circuit reopens.

class State¶

Bases: enum.IntEnum

Enum where members are also (and must be) ints

Initialize self. See help(type(self)) for accurate signature.

CLOSED = 0¶: The closed state.

HALF_OPEN = 1¶: The half-open state.

OPEN = 2¶: The open state.

__call__[T, **P](

f: collections.abc.Callable[P, collections.abc.Awaitable[T]],

/,

*,

timer: asyncutils._internal.prots.Timer = ...,

default: T = ...,

) → collections.abc.Callable[P, types.CoroutineType[Any, Any, T]][source]¶: Apply the circuit breaker to a function f returning an awaitable, and return a wrapper function with the same signature that strictly returns coroutines.

timer (default time.monotonic()) is used to get the current time to calculate the timeout.

If passed, default is returned if an expected exception is raised, also suppressing that exception.

Caution

Care should be taken when applying the same circuit breaker to multiple functions, as the calls counters will be shared.

property fails: int¶: Current count of consecutive failures.

property name: str¶: The name of the circuit breaker, to be shown in error messages.

property state: State¶: The current state of the circuit breaker.

class asyncutils.altlocks.DynamicThrottle( init_rate: float, min_rate: float = ..., max_rate: float = ..., window: int | None = ..., *, ubound: float | None = ..., lbound: float | None = ..., ufactor: float | None = ..., lfactor: float | None = ..., jitter: float | None = ..., timer: asyncutils._internal.prots.Timer = ..., rand: collections.abc.Callable[[float], float] = ..., )[source]¶

Limit the rate of a function being called.