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 
32 mod layer;
33 mod make;
34 mod service;
35 
36 #[cfg(test)]
37 mod test;
38 
39 pub use layer::MakeBalanceLayer;
40 pub use make::{MakeBalance, MakeFuture};
41 pub use service::Balance;
42