Implementation:Vespa engine Vespa FRTConnectionPool Constructor

Field	Value
Sources	Vespa
Domains	Configuration, Distributed_Systems
Type	API Doc
Last Updated	2026-02-09 12:00 GMT

Overview

FRTConnectionPool manages a pool of FRT connections to multiple config servers with health-aware selection and automatic failover. FRTConfigAgent processes config responses from the server and updates local config holders with proper error handling and backoff.

Description

The FRTConnectionPool constructor initializes a set of FRT connections to config servers defined by a ServerSpec. For each host in the server specification, it creates an FRTConnection instance, indexed by an FRTConnectionKey (which preserves insertion order for consistency with the Java implementation). It also creates an FRT_Supervisor to manage the underlying FNET transport.

The connection pool provides two selection strategies via getCurrent():

Round-robin (when hostname is empty): Cycles through ready connections using _selectIdx
Hash-based (when hostname is set): Uses Java-compatible string hashing of the hostname to deterministically select a server

Connections are classified as ready (not suspended) or suspended (experiencing errors). The pool prefers ready connections but falls back to suspended connections when none are available.

The FRTConfigAgent is constructed with a config holder and timing values. It processes responses from the config server:

OK responses: Resets failure counters, checks if the generation or content has changed via xxhash64, and pushes updates to the holder
Error responses: Increments the failure counter, applies bounded exponential backoff, and adjusts timeouts

Code Reference

Source Locations

Repository: vespa-engine/vespa
FRTConnectionPool header: config/src/vespa/config/frt/frtconnectionpool.h (line 40)
FRTConnectionPool implementation: config/src/vespa/config/frt/frtconnectionpool.cpp
FRTConfigAgent header: config/src/vespa/config/frt/frtconfigagent.h (lines 32--34)
FRTConfigAgent implementation: config/src/vespa/config/frt/frtconfigagent.cpp

FRTConnectionPool Signature

FRTConnectionPool(FNET_Transport & transport,
                  const ServerSpec & spec,
                  const TimingValues & timingValues);

FRTConfigAgent Signature

FRTConfigAgent(std::shared_ptr<IConfigHolder> holder,
               const TimingValues & timingValues);

void handleResponse(const ConfigRequest & request,
                    std::unique_ptr<ConfigResponse> response);

FRTConnectionPool Constructor Implementation

FRTConnectionPool::FRTConnectionPool(FNET_Transport & transport,
                                     const ServerSpec & spec,
                                     const TimingValues & timingValues)
    : _supervisor(std::make_unique<FRT_Supervisor>(&transport)),
      _selectIdx(0),
      _hostname("")
{
    for (size_t i(0); i < spec.numHosts(); i++) {
        FRTConnectionKey key(i, spec.getHost(i));
        _connections[key] = std::make_shared<FRTConnection>(
            spec.getHost(i), *_supervisor, timingValues);
    }
    setHostname();
}

FRTConfigAgent handleResponse Implementation

void
FRTConfigAgent::handleResponse(const ConfigRequest & request,
                               std::unique_ptr<ConfigResponse> response)
{
    if (response->validateResponse() && !response->isError()) {
        handleOKResponse(request, std::move(response));
    } else {
        handleErrorResponse(request, std::move(response));
    }
}

I/O Contract

FRTConnectionPool Constructor Inputs

Name	Type	Required	Description
`transport`	`FNET_Transport &`	Yes	The FNET transport layer that handles network I/O. Must remain valid for the lifetime of the pool.
`spec`	`const ServerSpec &`	Yes	The server specification containing one or more config server addresses in the form `tcp/hostname:port`.
`timingValues`	`const TimingValues &`	Yes	Timing parameters for connection suspension, retry delays, and timeouts.

FRTConfigAgent Constructor Inputs

Name	Type	Required	Description
`holder`	`std::shared_ptr<IConfigHolder>`	Yes	The config holder that receives config updates for consumption by subscriptions.
`timingValues`	`const TimingValues &`	Yes	Timing parameters governing success/error delays, timeouts, and backoff multipliers.

FRTConnectionPool Private Members

Name	Type	Description
`_supervisor`	`std::unique_ptr<FRT_Supervisor>`	Manages RPC connections through the FNET transport layer.
`_selectIdx`	`int`	Current index for round-robin connection selection.
`_hostname`	`std::string`	Local hostname used for hash-based connection selection. Empty string triggers round-robin mode.
`_connections`	`ConnectionMap`	Ordered map from `FRTConnectionKey` to `FRTConnection::SP`. Preserves insertion order.

FRTConfigAgent Private Members

Name	Type	Description
`_holder`	`std::shared_ptr<IConfigHolder>`	Receives config updates (`ConfigUpdate` objects) when new generations arrive.
`_timingValues`	`const TimingValues`	Immutable timing configuration controlling delays and timeouts.
`_configState`	`ConfigState`	Current config state tracking generation number and content hash.
`_latest`	`ConfigValue`	The most recent config value, used for change detection via `xxhash64`.
`_waitTime`	`duration`	Current delay before the next config request.
`_numConfigured`	`uint64_t`	Count of successful config updates received. Zero means the process has not yet been configured.
`_failedRequests`	`unsigned int`	Count of consecutive failed requests. Used as a multiplier for backoff.
`_nextTimeout`	`duration`	Timeout for the next config request (varies between success, error, and initial timeouts).

Key Methods

Connection Selection

// Round-robin: cycles through ready sources, falls back to suspended
FRTConnection* FRTConnectionPool::getNextRoundRobin();

// Hash-based: deterministic selection based on hostname hash
FRTConnection* FRTConnectionPool::getNextHashBased();

// Dispatches to round-robin or hash-based depending on _hostname
Connection* FRTConnectionPool::getCurrent();

Health Classification

// Returns connections whose suspension has expired
std::vector<FRTConnection*> getReadySources() const;

// Returns connections that are currently suspended
std::vector<FRTConnection*> getSuspendedSources() const;

Error Backoff

void FRTConfigAgent::setWaitTime(duration delay, int multiplier) {
    _waitTime = _timingValues.fixedDelay + (multiplier * delay);
}

The multiplier is capped at _timingValues.maxDelayMultiplier to bound the maximum backoff:

int multiplier = std::min(_failedRequests, _timingValues.maxDelayMultiplier);

Usage Examples

Typical Connection Pool Lifecycle

#include <vespa/config/frt/frtconnectionpool.h>
#include <vespa/fnet/transport.h>

using namespace config;

// Create transport and server spec
FNET_Transport transport;
transport.Start();
ServerSpec spec("tcp/cfg1.example.com:19070,tcp/cfg2.example.com:19070");
TimingValues timing;

// Create connection pool -- connects to both servers
FRTConnectionPool pool(transport, spec, timing);

// Get the current best connection (round-robin or hash-based)
Connection* conn = pool.getCurrent();

// The pool automatically skips suspended connections
// and falls back if all are suspended

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment