tower/balance/mod.rs
1//! Middleware that allows balancing load among multiple services.
2//!
3//! In larger systems, multiple endpoints are often available for a given service. As load
4//! increases, you want to ensure that that load is spread evenly across the available services.
5//! Otherwise, clients could see spikes in latency if their request goes to a particularly loaded
6//! service, even when spare capacity is available to handle that request elsewhere.
7//!
8//! This module provides the [`p2c`] middleware, which implements the "[Power of
9//! Two Random Choices]" algorithm. This is a simple but robust technique for
10//! spreading load across services with only inexact load measurements. Use this
11//! if the set of available services is not within your control, and you simply
12//! want to spread load among that set of services.
13//!
14//! [Power of Two Random Choices]: http://www.eecs.harvard.edu/~michaelm/postscripts/handbook2001.pdf
15//!
16//! # Examples
17//!
18//! ```rust
19//! # #[cfg(feature = "util")]
20//! # #[cfg(feature = "load")]
21//! # fn warnings_are_errors() {
22//! use tower::balance::p2c::Balance;
23//! use tower::load::Load;
24//! use tower::{Service, ServiceExt};
25//! use futures_util::pin_mut;
26//! # use futures_core::Stream;
27//! # use futures_util::StreamExt;
28//!
29//! async fn spread<Req, S: Service<Req> + Load>(svc1: S, svc2: S, reqs: impl Stream<Item = Req>)
30//! where
31//! S::Error: Into<tower::BoxError>,
32//! # // this bound is pretty unfortunate, and the compiler does _not_ help
33//! S::Metric: std::fmt::Debug,
34//! {
35//! // Spread load evenly across the two services
36//! let p2c = Balance::new(tower::discover::ServiceList::new(vec![svc1, svc2]));
37//!
38//! // Issue all the requests that come in.
39//! // Some will go to svc1, some will go to svc2.
40//! pin_mut!(reqs);
41//! let mut responses = p2c.call_all(reqs);
42//! while let Some(rsp) = responses.next().await {
43//! // ...
44//! }
45//! }
46//! # }
47//! ```
48
49pub mod error;
50pub mod p2c;