Struct tower::ready_cache::cache::ReadyCache
source · pub struct ReadyCache<K, S, Req>{ /* private fields */ }
Expand description
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§
source§impl<K, S, Req> ReadyCache<K, S, Req>
impl<K, S, Req> ReadyCache<K, S, Req>
sourcepub fn pending_len(&self) -> usize
pub fn pending_len(&self) -> usize
Returns the number of services in the unready set.
sourcepub fn pending_contains<Q: Hash + Equivalent<K>>(&self, key: &Q) -> bool
pub fn pending_contains<Q: Hash + Equivalent<K>>(&self, key: &Q) -> bool
Returns true iff the given key is in the unready set.
sourcepub fn get_ready<Q: Hash + Equivalent<K>>(
&self,
key: &Q,
) -> Option<(usize, &K, &S)>
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.
sourcepub fn get_ready_mut<Q: Hash + Equivalent<K>>(
&mut self,
key: &Q,
) -> Option<(usize, &K, &mut S)>
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.
sourcepub fn get_ready_index(&self, idx: usize) -> Option<(&K, &S)>
pub fn get_ready_index(&self, idx: usize) -> Option<(&K, &S)>
Obtains a reference to a service in the ready set by index.
sourcepub fn get_ready_index_mut(&mut self, idx: usize) -> Option<(&mut K, &mut S)>
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.
sourcepub fn evict<Q: Hash + Equivalent<K>>(&mut self, key: &Q) -> bool
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.
source§impl<K, S, Req> ReadyCache<K, S, Req>
impl<K, S, Req> ReadyCache<K, S, Req>
sourcepub fn push(&mut self, key: K, svc: S)
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.
sourcepub fn poll_pending(
&mut self,
cx: &mut Context<'_>,
) -> Poll<Result<(), Failed<K>>>
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.
sourcepub fn check_ready<Q: Hash + Equivalent<K>>(
&mut self,
cx: &mut Context<'_>,
key: &Q,
) -> Result<bool, Failed<K>>
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.
sourcepub fn check_ready_index(
&mut self,
cx: &mut Context<'_>,
index: usize,
) -> Result<bool, Failed<K>>
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.