Struct tower::ready_cache::cache::ReadyCache

pub struct ReadyCache<K, S, Req>where
    K: Eq + Hash,{ /* private fields */ }

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 abitrarily 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 indicats 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>where
    K: Eq + Hash,

pub fn len(&self) -> usize

Returns the total number of services in the cache.

pub fn is_empty(&self) -> bool

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

pub fn ready_len(&self) -> usize

Returns the number of services in the ready set.

pub fn pending_len(&self) -> usize

Returns the number of services in the unready set.

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

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

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

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

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

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

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

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

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

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

pub fn evict<Q: Hash + Equivalent<K>>(&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> ReadyCache<K, S, Req>where
    K: Clone + Eq + Hash,
    S: Service<Req>,
    <S as Service<Req>>::Error: Into<BoxError>,
    S::Error: Into<BoxError>,

pub fn push(&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.

pub fn poll_pending(
    &mut self,
    cx: &mut Context<'_>
) -> Poll<Result<(), 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.

pub fn check_ready<Q: Hash + Equivalent<K>>(
    &mut self,
    cx: &mut Context<'_>,
    key: &Q
) -> Result<bool, 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.

pub fn check_ready_index(
    &mut self,
    cx: &mut Context<'_>,
    index: usize
) -> Result<bool, 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.

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

Calls a ready service by key.

Panics

If the specified key does not exist in the ready

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

Calls a ready service by index.

Panics

If the specified index is out of range.

Trait Implementations

impl<K, S, Req> Debug for ReadyCache<K, S, Req>where
    K: Debug + Eq + Hash,
    S: Debug,

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

Formats the value using the given formatter.

impl<K, S, Req> Default for ReadyCache<K, S, Req>where
    K: Eq + Hash,
    S: Service<Req>,

fn default() -> Self

Returns the “default value” for a type.

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