Package org.asynchttpclient

Enum LoadBalance

    • Enum Constant Detail

      • DEFAULT

        public static final LoadBalance DEFAULT
        Default behavior. The address list returned by DNS is used in its natural order: a new connection always targets the first address and only falls back to the next one when a TCP connection attempt fails. Combined with connection pooling (keyed by host), this means that with keep-alive enabled essentially all traffic to a host stays on the first reachable IP.

        To spread traffic across a host's IPs in this mode, configure a resolver that rotates its results, such as RoundRobinInetAddressResolver; the client keeps targeting the first address, and the resolver is what varies which IP that is.

      • ROUND_ROBIN

        public static final LoadBalance ROUND_ROBIN
        Strict per-request round-robin across the host's resolved IPs.

        For each request, the client rotates which resolved IP is targeted first (TCP failover to the remaining IPs is preserved) and makes connection reuse IP-aware, so that pooled HTTP/1.1 connections and multiplexed HTTP/2 connections are kept and reused per IP rather than per host. The net effect is that consecutive requests to a multi-IP host are spread evenly across all of its addresses, even when connections are kept alive.

        Notes:

        • Has no effect for hosts that resolve to a single address, literal-IP hosts, requests with an explicit address, or requests routed through a proxy (HTTP or SOCKS) — the socket is established to the proxy, not directly to the rotated target IPs. (Round-robin still applies when the proxy is bypassed for the host.)
        • Connection limits (maxConnectionsPerHost) are enforced per host, not per IP: at most that many HTTP/2 connections are kept open to a host at once, spread across that many of its resolved IPs (see the cap note below).
        • For HTTP/2 this mode deliberately opens more than one connection to the same host and port — up to one per resolved IP, bounded by maxConnectionsPerHost — so streams can be spread across the host's backends. That is a conscious deviation from RFC 9113 (and RFC 7540) Section 9.1, which recommends that clients SHOULD NOT open more than one HTTP/2 connection to a given host and port pair. DEFAULT mode preserves the standard single-connection-per-origin behavior.
        • When maxConnectionsPerHost (call it K) is smaller than the number of resolved IPs, the cap wins over full spreading: at most K HTTP/2 connections are opened, to the first K rotated IPs, and a request pinned to any further IP cannot acquire a per-host permit — it multiplexes onto one of those K sibling connections (multiplexing onto an existing connection takes no permit) instead of opening another, failing with TooManyConnectionsPerHostException only if none is available. Those K connections are held open (kept alive by HTTP/2 PING), so they stay pinned to their K IPs rather than rotating across all of them; set maxConnectionsPerHost at least as large as the resolved-IP count for full per-IP spreading. The default is unlimited, so this bound only applies when a finite per-host limit is configured.
        • Since the per-host permit is held for the connection's lifetime, each live round-robin HTTP/2 connection also occupies a global maxConnections slot until it closes, and pool connectionTtl/idle reaping do not apply (these connections live in the HTTP/2 registry, kept alive by PING, until GOAWAY or the connection drops). When a GOAWAY starts draining a connection its permit is released immediately, so a replacement can be opened without waiting for in-flight streams to finish.
        • The address order comes straight from the configured InetNameResolver; this mode does not re-sort it. For the rotation to map consistently across requests, use a resolver that returns the addresses in a stable order and does not deliberately reorder them between resolutions (for example DnsNameResolver). Do not pair this mode with a resolver that intentionally rotates its results, such as RoundRobinInetAddressResolver — that one is meant for DEFAULT mode, where it provides the spreading instead.
        • The rotation is applied on top of the failed-IP cooldown (AsyncHttpClientConfig.isFailedIpCooldownEnabled()), which briefly deprioritizes a recently-failed IP. That cooldown is a separate, mode-independent feature — it also applies in DEFAULT mode — so it is documented on the config getter rather than here.

    • Method Detail

      • values

        public static LoadBalance[] values()
        Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows: 
        for (LoadBalance c : LoadBalance.values())
    System.out.println(c);
        Returns:
        an array containing the constants of this enum type, in the order they are declared

      • valueOf

        public static LoadBalance valueOf​(String name)
        Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
        Parameters:
        name - the name of the enum constant to be returned.
        Returns:
        the enum constant with the specified name
        Throws:
        IllegalArgumentException - if this enum type has no constant with the specified name
        NullPointerException - if the argument is null