Struct LoadBalancer

pub struct LoadBalancer<S> {
    pub health_check_frequency: Option<Duration>,
    pub update_frequency: Option<Duration>,
    pub parallel_health_check: bool,
    /* private fields */
}

A LoadBalancer instance contains the service discovery, health check and backend selection all together.

In order to run service discovery and health check at the designated frequencies, the LoadBalancer needs to be run as a pingora_core::services::background::BackgroundService.

Fields

health_check_frequency: Option<Duration>

How frequent the health check logic (if set) should run.

If None, the health check logic will only run once at the beginning.

update_frequency: Option<Duration>

How frequent the service discovery should run.

If None, the service discovery will only run once at the beginning.

parallel_health_check: bool

Whether to run health check to all backends in parallel. Default is false.

Implementations

impl<'a, S> LoadBalancer<S>

where S: BackendSelection + 'static, S::Iter: BackendIter,

pub fn try_from_iter<A, T: IntoIterator<Item = A>>(iter: T) -> IoResult<Self>

where A: ToSocketAddrs,

Build a LoadBalancer with static backends created from the iter.

Note: ToSocketAddrs will invoke blocking network IO for DNS lookup if the input cannot be directly parsed as SocketAddr.

pub fn from_backends(backends: Backends) -> Self

Build a LoadBalancer with the given Backends.

pub async fn update(&self) -> Result<()>

Run the service discovery and update the selection algorithm.

This function will be called every update_frequency if this LoadBalancer instance is running as a background service.

pub fn select(&self, key: &[u8], max_iterations: usize) -> Option<Backend>

Return the first healthy Backend according to the selection algorithm and the health check results.

The key is used for hash based selection and is ignored if the selection is random or round robin.

the max_iterations is there to bound the search time for the next Backend. In certain algorithm like Ketama hashing, the search for the next backend is linear and could take a lot steps.

pub fn select_with<F>( &self, key: &[u8], max_iterations: usize, accept: F, ) -> Option<Backend>

where F: Fn(&Backend, bool) -> bool,

Similar to Self::select, return the first healthy Backend according to the selection algorithm and the user defined accept function.

The accept function takes two inputs, the backend being selected and the internal health of that backend. The function can do things like ignoring the internal health checks or skipping this backend because it failed before. The accept function is called multiple times iterating over backends until it returns true.

pub fn set_health_check( &mut self, hc: Box<dyn HealthCheck + Send + Sync + 'static>, )

Set the health check method. See health_check.

pub fn backends(&self) -> &Backends

Access the Backends of this LoadBalancer

Trait Implementations

impl<S: Send + Sync + BackendSelection + 'static> BackgroundService for LoadBalancer<S>

where S::Iter: BackendIter,

fn start<'life0, 'async_trait>( &'life0 self, shutdown: ShutdownWatch, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

This function is called when the pingora server tries to start all the services. The background service can return at anytime or wait for the shutdown signal.