Implementation:Vespa engine Vespa ConfigHandle GetConfig

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

Overview

ConfigHandle::getConfig is a template method that deserializes the current configuration payload into a strongly-typed config object, providing safe access to the latest fetched configuration snapshot.

Description

The getConfig() method on ConfigHandle<ConfigType> is the final step in the config subscription lifecycle where configuration data is materialized into a usable C++ object. The method accesses the underlying ConfigSubscription (held as a shared pointer), retrieves the current ConfigValue, and constructs a new instance of ConfigType from it.

The method enforces strict preconditions:

If the ConfigSubscriber has not yet been polled (no call to nextConfig() or nextGeneration()), the method throws a ConfigRuntimeException
If the configuration payload is malformed or cannot be parsed into ConfigType, it throws an InvalidConfigException

The handle also provides isChanged(), which returns whether this specific config subscription had its content change in the most recent generation update. This allows callers to efficiently skip reconfiguration when only other subscribed configs have changed.

Code Reference

Source Location

Repository: vespa-engine/vespa
File: config/src/vespa/config/subscription/confighandle.h
Line: 33

Signature

template <typename ConfigType>
std::unique_ptr<ConfigType> ConfigHandle<ConfigType>::getConfig() const;

Change Detection

template <typename ConfigType>
bool ConfigHandle<ConfigType>::isChanged() const;

Class Definition

template <typename ConfigType>
class ConfigHandle
{
public:
    typedef std::unique_ptr<ConfigHandle<ConfigType>> UP;

    explicit ConfigHandle(std::shared_ptr<ConfigSubscription> subscription);
    ~ConfigHandle();

    std::unique_ptr<ConfigType> getConfig() const;
    bool isChanged() const;

private:
    std::shared_ptr<ConfigSubscription> _subscription;
};

I/O Contract

Inputs

The method takes no parameters. It reads from the internal _subscription member, which holds a std::shared_ptr<ConfigSubscription>.

Outputs

Name	Type	Description
return	`std::unique_ptr<ConfigType>`	A newly constructed, fully populated configuration object representing the current config snapshot. Ownership is transferred to the caller.

Exceptions

Exception	Condition
`ConfigRuntimeException`	The `ConfigSubscriber` has not yet been polled via `nextConfig()` or `nextGeneration()`. No config data is available.
`InvalidConfigException`	The configuration payload could not be parsed or instantiated into the given `ConfigType`. This indicates a schema mismatch or corrupt payload.

Private Members

Name	Type	Description
`_subscription`	`std::shared_ptr<ConfigSubscription>`	Shared reference to the underlying subscription. Provides access to the current `ConfigValue` payload and change detection state.

Usage Examples

Basic Config Retrieval

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

using namespace config;

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

subscriber.nextConfig();

// Deserialize and retrieve the typed config
std::unique_ptr<MyappConfig> cfg = handle->getConfig();

// Access config fields with full type safety
int port = cfg->port;
std::string name = cfg->name;

Selective Reconfiguration Using isChanged

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

subscriber.nextConfig();

// Main reconfiguration loop
while (!subscriber.isClosed()) {
    if (subscriber.nextConfig(60s)) {
        // Only reconfigure components whose config actually changed
        if (appHandle->isChanged()) {
            auto appCfg = appHandle->getConfig();
            reconfigureApp(*appCfg);
        }
        if (rankHandle->isChanged()) {
            auto rankCfg = rankHandle->getConfig();
            reconfigureRanking(*rankCfg);
        }
    }
}

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment