Struct tower::ready_cache::cache::ReadyCache

source ·
pub struct ReadyCache<K, S, Req>
where K: Eq + Hash,
{ /* 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>
where K: Eq + Hash,

source

pub fn len(&self) -> usize

Returns the total number of services in the cache.

source

pub fn is_empty(&self) -> bool

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

source

pub fn ready_len(&self) -> usize

Returns the number of services in the ready set.

source

pub fn pending_len(&self) -> usize

Returns the number of services in the unready set.

source

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

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

source

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.

source

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.

source

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

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

source

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.

source

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>
where K: Clone + Eq + Hash, S: Service<Req>, <S as Service<Req>>::Error: Into<BoxError>, S::Error: Into<BoxError>,

source

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.

source

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.

source

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.

source

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.

source

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

source

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§

source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

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

Auto Trait Implementations§

§

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>
where K: Send, S: Send, Req: Send,

§

impl<K, S, Req> Sync for ReadyCache<K, S, Req>
where K: Send + Sync, S: Send + Sync, Req: Send + Sync,

§

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

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more