Struct `ReadyCache`

struct ReadyCache<K, S, Req> { ... }
where
    K: Eq + Hash

Drives readiness over a set of services.

The cache maintains two internal data structures:

a set of pending services that have not yet become ready; and
a set of ready services that have previously polled ready.

As each S typed Service is added to the cache via ReadyCache::push, it is added to the pending set. As ReadyCache::poll_pending is invoked, pending services are polled and added to the ready set.

ReadyCache::call_ready (or ReadyCache::call_ready_index) dispatches a request to the specified service, but panics if the specified service is not in the ready set. The ReadyCache::check_* functions can be used to ensure that a service is ready before dispatching a request.

The ready set can hold services for an arbitrarily long time. During this time, the runtime may process events that invalidate that ready state (for instance, if a keepalive detects a lost connection). In such cases, callers should use ReadyCache::check_ready (or ReadyCache::check_ready_index) immediately before dispatching a request to ensure that the service has not become unavailable.

Once ReadyCache::call_ready* is invoked, the service is placed back into the pending set to be driven to readiness again.

When ReadyCache::check_ready* returns false, it indicates that the specified service is not ready. If an error is returned, this indicates that the server failed and has been removed from the cache entirely.

ReadyCache::evict can be used to remove a service from the cache (by key), though the service may not be dropped (if it is currently pending) until ReadyCache::poll_pending is invoked.

Note that the by-index accessors are provided to support use cases (like power-of-two-choices load balancing) where the caller does not care to keep track of each service's key. Instead, it needs only to access some ready service. In such a case, it should be noted that calls to ReadyCache::poll_pending and ReadyCache::evict may perturb the order of the ready set, so any cached indexes should be discarded after such a call.

Implementations

`impl<K, S, Req> ReadyCache<K, S, Req>`

fn push(self: &mut Self, key: K, svc: S)

Pushes a new service onto the pending set.

The service will be promoted to the ready set as poll_pending is invoked.

Note that this does not remove services from the ready set. Once the old service is used, it will be dropped instead of being added back to the pending set; OR, when the new service becomes ready, it will replace the prior service in the ready set.

fn poll_pending(self: &mut Self, cx: &mut Context<'_>) -> Poll<Result<(), error::Failed<K>>>

Polls services pending readiness, adding ready services to the ready set.

Returns Poll::Ready when there are no remaining unready services. poll_pending should be called again after push or call_ready_index are invoked.

Failures indicate that an individual pending service failed to become ready (and has been removed from the cache). In such a case, poll_pending should typically be called again to continue driving pending services to readiness.

fn check_ready<Q: Hash + Equivalent<K>>(self: &mut Self, cx: &mut Context<'_>, key: &Q) -> Result<bool, error::Failed<K>>

Checks whether the referenced endpoint is ready.

Returns true if the endpoint is ready and false if it is not. An error is returned if the endpoint fails.

fn check_ready_index(self: &mut Self, cx: &mut Context<'_>, index: usize) -> Result<bool, error::Failed<K>>

Checks whether the referenced endpoint is ready.

If the service is no longer ready, it is moved back into the pending set and false is returned.

If the service errors, it is removed and dropped and the error is returned.

fn call_ready<Q: Hash + Equivalent<K>>(self: &mut Self, key: &Q, req: Req) -> <S as >::Future

Calls a ready service by key.

Panics

If the specified key does not exist in the ready

fn call_ready_index(self: &mut Self, index: usize, req: Req) -> <S as >::Future

Calls a ready service by index.

Panics

If the specified index is out of range.

`impl<K, S, Req> ReadyCache<K, S, Req>`

fn len(self: &Self) -> usize

Returns the total number of services in the cache.

fn is_empty(self: &Self) -> bool

Returns whether or not there are any services in the cache.

fn ready_len(self: &Self) -> usize

Returns the number of services in the ready set.

fn pending_len(self: &Self) -> usize

Returns the number of services in the unready set.

fn pending_contains<Q: Hash + Equivalent<K>>(self: &Self, key: &Q) -> bool

Returns true iff the given key is in the unready set.

fn get_ready<Q: Hash + Equivalent<K>>(self: &Self, key: &Q) -> Option<(usize, &K, &S)>

Obtains a reference to a service in the ready set by key.

fn get_ready_mut<Q: Hash + Equivalent<K>>(self: &mut Self, key: &Q) -> Option<(usize, &K, &mut S)>

Obtains a mutable reference to a service in the ready set by key.

fn get_ready_index(self: &Self, idx: usize) -> Option<(&K, &S)>

Obtains a reference to a service in the ready set by index.

fn get_ready_index_mut(self: &mut Self, idx: usize) -> Option<(&K, &mut S)>

Obtains a mutable reference to a service in the ready set by index.

fn iter_ready(self: &Self) -> impl Iterator<Item = (&K, &S)>

Returns an iterator over the ready keys and services.

fn iter_ready_mut(self: &mut Self) -> impl Iterator<Item = (&K, &mut S)>

Returns a mutable iterator over the ready keys and services.

fn evict<Q: Hash + Equivalent<K>>(self: &mut Self, key: &Q) -> bool

Evicts an item from the cache.

Returns true if a service was marked for eviction.

Services are dropped from the ready set immediately. Services in the pending set are marked for cancellation, but ReadyCache::poll_pending must be called to cause the service to be dropped.

`impl<K, S, Req> Debug for ReadyCache<K, S, Req>`

fn fmt(self: &Self, f: &mut fmt::Formatter<'_>) -> fmt::Result

`impl<K, S, Req> Default for ReadyCache<K, S, Req>`

fn default() -> Self

`impl<K, S, Req> Freeze for ReadyCache<K, S, Req>`

`impl<K, S, Req> RefUnwindSafe for ReadyCache<K, S, Req>`

`impl<K, S, Req> Send for ReadyCache<K, S, Req>`

`impl<K, S, Req> Sync for ReadyCache<K, S, Req>`

`impl<K, S, Req> UnwindSafe for ReadyCache<K, S, Req>`

`impl<S, K: Eq + Hash, Req> Unpin for ReadyCache<K, S, Req>`

`impl<T> Any for ReadyCache<K, S, Req>`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for ReadyCache<K, S, Req>`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for ReadyCache<K, S, Req>`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> From for ReadyCache<K, S, Req>`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T> Instrument for ReadyCache<K, S, Req>`

`impl<T> WithSubscriber for ReadyCache<K, S, Req>`

`impl<T, U> Into for ReadyCache<K, S, Req>`

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

`impl<T, U> TryFrom for ReadyCache<K, S, Req>`

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

`impl<T, U> TryInto for ReadyCache<K, S, Req>`

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>