Module multiplex 

Available on crate feature net only.

Multiplexing connection pool.

MultiplexPool keeps every connection in storage and hands out a cheap MultiplexedConnection that shares a connection through &self. A single connection serves up to min(max_streams_per_connection, MaxConcurrency) concurrent users, where MaxConcurrency is the connection’s advertised capacity (usize::MAX when unset) and the pool’s own cap is unset by default, so the peer decides. The exclusive super::LruDropPool is the special case of capacity 1 for owned connections.

Because the connector stack runs for every request, a MultiplexedConnection is established, serves its single request, and is dropped, so a MultiplexedConnection is bound to exactly one connection (its super::ExtensionsRef forwards to that connection, which is required for extension propagation such as the negotiated http version) and concurrency is metered by counting live handouts. A MultiplexedConnection is not meant to outlive a single logical request and when it does it should only be used for one input/request at a time.

Checking out a connection does not look at every connection of the ID. Each ID keeps an index of its connections that have a free stream slot, in creation order, and the selection strategy picks from it: the cost of a checkout does not grow with the number of idle connections an ID has accumulated. Selection prefers earlier connections, so a burst that opened many connections leaves the later ones untouched and idle, where the idle timeout reaps them (see MultiplexPool::with_idle_timeout).

Connections are not limited by default. With a limit per ID or in total (see MultiplexPool::with_max_connections_per_id and MultiplexPool::with_max_connections_total), a checkout that needs a new connection at the limit waits for a slot or, as the SaturationPolicy allows, replaces an idle connection: of its own ID at the ID’s limit, of any ID at the total one.

A checkout that finds no room waits, first come first served, in every lane it can be served from: a released stream wakes the first waiter of its lane, a capacity change of a connection wakes all of them, and newcomers never take capacity ahead of them. A waiter that leaves without using a wake passes it on. An idle connection goes to the checkout that arrived first among its lane’s front and the fronts of those waiting to evict it, for the total limit or for its id’s: whoever runs first, the others give way to it, and it is told; once it leaves, they are.

A checkout that finds no free stream on a multiplexed lane waits for the connects already in flight for its lanes while they bring streams for everyone waiting, and dials otherwise: a burst opens the connections it needs at once, not one each. What a new connection takes is that of the newest connection of the lanes, else of the id’s last one, else, for a request expecting to multiplex (see MultiplexPool::with_streams_hint), that of the pool’s last multiplexed one or the hint’s guess; a guess dials a few connects before one shows its own. A connect failing fails the checkouts that waited for it and saw none land, if their requests would fail alike, and has the others dial their own. A checkout waiting for connects holds no connection slot, and dials its own once MultiplexPool::with_max_wait_before_dial or its caller’s deadline is up, unless MultiplexPool::with_max_connecting_per_id caps the connects in flight.

Structs

MultiplexPool

Connection pool that multiplexes concurrent users over shared connections.

MultiplexSlot

The share of a MultiplexPool’s limits a new connection takes: the create permit of MultiplexPool::get_conn. The connection keeps it while stored.

MultiplexedConnection

A cheap handle to a shared connection in a MultiplexPool.

Enums

MuxSelection

Strategy used to pick a connection among several that share the same ConnID and still have stream capacity.

SaturationPolicy

What a MultiplexPool at a connection limit does for a checkout that needs a new connection: wait, or replace an idle connection, of its own id at the id’s limit and of any id at the total one.

Type Aliases

StreamsHint

Whether a request of an id expects a new connection to multiplex, with a guess of its streams for a pool that knows none: see MultiplexPool::with_streams_hint.