Implementation:Vespa engine Vespa ConfigSubscriber Subscribe

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

Overview

ConfigSubscriber::subscribe is a template method that registers interest in a specific configuration type and returns a type-safe handle for later retrieval.

Description

The subscribe method is the entry point for declaring configuration dependencies in Vespa's C++ config client library. It is a template method parameterized on the configuration type (ConfigType), which allows compile-time enforcement of type safety. The method takes a configId string that identifies the specific configuration instance (e.g., a particular search cluster or document type) and an optional timeout.

Internally, the method delegates to the ConfigSubscriptionSet, which creates a ConfigSubscription through the config manager. The subscription set enforces a state machine: subscriptions can only be added while the set is in the OPEN state. Once nextConfig() or nextGeneration() is called, the state transitions to FROZEN and any further calls to subscribe will throw a ConfigRuntimeException.

The returned ConfigHandle holds a shared pointer to the underlying ConfigSubscription and provides type-safe access to the deserialized configuration object through its getConfig() method.

Code Reference

Source Location

Repository: vespa-engine/vespa
File: config/src/vespa/config/subscription/configsubscriber.h
Lines: 81--83

Includes

#include "confighandle.h"
#include "subscriptionid.h"
#include "configsubscription.h"
#include "configsubscriptionset.h"
#include "configprovider.h"
#include "sourcespec.h"
#include <vespa/config/common/timingvalues.h>

Namespace

namespace config {

Signature

template <typename ConfigType>
std::unique_ptr<ConfigHandle<ConfigType>>
ConfigSubscriber::subscribe(const std::string & configId,
                            vespalib::duration timeout = DEFAULT_SUBSCRIBE_TIMEOUT);

I/O Contract

Inputs

Name	Type	Required	Description
`configId`	`const std::string &`	Yes	The configuration identifier that names the specific config instance to subscribe to (e.g., `"search/cluster.music"`)
`timeout`	`vespalib::duration`	No	Maximum time to wait for the initial subscription to be established. Defaults to `DEFAULT_SUBSCRIBE_TIMEOUT`.

Template Parameters

Name	Description
`ConfigType`	The generated config class corresponding to a `.def` file. Must provide a static `getDefName()` and `getDefNamespace()`.

Outputs

Name	Type	Description
return	`std::unique_ptr<ConfigHandle<ConfigType>>`	A type-safe handle that can be used to retrieve the current configuration snapshot after calling `nextConfig()` or `nextGeneration()`.

Exceptions

Exception	Condition
`ConfigTimeoutException`	The subscription could not be established within the specified timeout.
`ConfigRuntimeException`	The subscriber has already been closed, or `nextConfig()`/`nextGeneration()` has already been called (subscriber is frozen).

Internal Delegation

The subscribe call follows this delegation chain:

ConfigSubscriber::subscribe<ConfigType>(configId, timeout)
ConfigSubscriptionSet::subscribe(ConfigKey, timeout) -- validates the set is in OPEN state, then calls the config manager
IConfigManager::subscribe(ConfigKey, timeout) -- creates the underlying ConfigSubscription with the appropriate source
Returns a ConfigHandle<ConfigType> wrapping the shared ConfigSubscription

Usage Examples

Basic Single-Config Subscription

#include <vespa/config/subscription/configsubscriber.h>
#include "config-myapp.h"  // Generated from myapp.def

using namespace config;

ConfigSubscriber subscriber(ServerSpec("tcp/configserver:19070"));
auto handle = subscriber.subscribe<MyappConfig>("myapp/instance1");

// Fetch the first config snapshot
subscriber.nextConfig();

// Retrieve the typed config object
auto cfg = handle->getConfig();

Multi-Config Subscription

#include <vespa/config/subscription/configsubscriber.h>
#include "config-myapp.h"
#include "config-ranking.h"

using namespace config;

ConfigSubscriber subscriber;
auto appHandle = subscriber.subscribe<MyappConfig>("myapp/instance1");
auto rankHandle = subscriber.subscribe<RankingConfig>("myapp/instance1");

// Both configs are fetched atomically at the same generation
subscriber.nextConfig();

auto appCfg = appHandle->getConfig();
auto rankCfg = rankHandle->getConfig();

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment