tower/balance/p2c/
mod.rs

1//! This module implements the "[Power of Two Random Choices]" load balancing algorithm.
2//!
3//! It is a simple but robust technique for spreading load across services with only inexact load
4//! measurements. As its name implies, whenever a request comes in, it samples two ready services
5//! at random, and issues the request to whichever service is less loaded. How loaded a service is
6//! is determined by the return value of [`Load`](crate::load::Load).
7//!
8//! As described in the [Finagle Guide][finagle]:
9//!
10//! > The algorithm randomly picks two services from the set of ready endpoints and
11//! > selects the least loaded of the two. By repeatedly using this strategy, we can
12//! > expect a manageable upper bound on the maximum load of any server.
13//! >
14//! > The maximum load variance between any two servers is bound by `ln(ln(n))` where
15//! > `n` is the number of servers in the cluster.
16//!
17//! The balance service and layer implementations rely on _service discovery_ to provide the
18//! underlying set of services to balance requests across. This happens through the
19//! [`Discover`](crate::discover::Discover) trait, which is essentially a [`Stream`] that indicates
20//! when services become available or go away. If you have a fixed set of services, consider using
21//! [`ServiceList`](crate::discover::ServiceList).
22//!
23//! Since the load balancer needs to perform _random_ choices, the constructors in this module
24//! usually come in two forms: one that uses randomness provided by the operating system, and one
25//! that lets you specify the random seed to use. Usually the former is what you'll want, though
26//! the latter may come in handy for reproducability or to reduce reliance on the operating system.
27//!
28//! [Power of Two Random Choices]: http://www.eecs.harvard.edu/~michaelm/postscripts/handbook2001.pdf
29//! [finagle]: https://twitter.github.io/finagle/guide/Clients.html#power-of-two-choices-p2c-least-loaded
30//! [`Stream`]: https://docs.rs/futures/0.3/futures/stream/trait.Stream.html
31
32mod layer;
33mod make;
34mod service;
35
36#[cfg(test)]
37mod test;
38
39pub use layer::MakeBalanceLayer;
40pub use make::{MakeBalance, MakeFuture};
41pub use service::Balance;