Implementation:Vespa engine Vespa ConfigSubscriber NextConfig

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

Overview

ConfigSubscriber::nextConfig is a blocking method that waits for a new configuration generation where at least one subscribed config has changed its content, returning a boolean indicating success.

Description

The nextConfig method is the primary synchronization point in the config subscription lifecycle. It blocks until all subscriptions have received configuration data from the same generation and at least one subscription has changed content compared to the previous generation.

Internally, nextConfig delegates to ConfigSubscriptionSet::acquireSnapshot(timeout, false), where the false parameter indicates that a content change is required (as opposed to nextGeneration which passes true to ignore the change requirement).

The acquireSnapshot method implements the following algorithm:

If the set is CLOSED, return false immediately
If the set is OPEN, transition to FROZEN (no more subscribes allowed)
Enter a polling loop that runs until the deadline:
1. For each subscription, call nextUpdate() to check for new data
2. Track how many subscriptions have a new generation and how many have changed content
3. Check if all subscriptions are at the same generation (in sync)
4. If in sync, all have a new generation, and at least one has changed content, break
5. Otherwise, sleep for up to 20ms (adjusted for system tick rate) and retry
If a consistent, newer generation was found, update the current generation, flip all subscriptions to their new state, and return true
Otherwise return false (timeout or closed)

A convenience variant nextConfigNow() calls nextConfig with a zero timeout for non-blocking polling.

Code Reference

Source Location

Repository: vespa-engine/vespa
File (declaration): config/src/vespa/config/subscription/configsubscriber.h
Line: 59
File (definition): config/src/vespa/config/subscription/configsubscriber.cpp
Lines: 20--24

Signature

bool ConfigSubscriber::nextConfig(vespalib::duration timeout = DEFAULT_NEXTCONFIG_TIMEOUT);

Convenience Variant

bool ConfigSubscriber::nextConfigNow() { return nextConfig(vespalib::duration::zero()); }

Internal Delegation

bool
ConfigSubscriber::nextConfig(vespalib::duration timeout)
{
    return _set.acquireSnapshot(timeout, false);
}

I/O Contract

Inputs

Name	Type	Required	Description
`timeout`	`vespalib::duration`	No	Maximum time to block waiting for a new config generation. Defaults to `DEFAULT_NEXTCONFIG_TIMEOUT`.

Outputs

Name	Type	Description
return	`bool`	`true` if a new configuration generation was obtained where at least one subscription has changed content. `false` if the timeout was reached or the subscriber has been closed.

Side Effects

On the first call, transitions the subscription set from OPEN to FROZEN. After this, no further subscribe() calls are allowed.
On success, updates the internal generation counter and flips all subscriptions to their new state (making config data available through handles).
Transitions the subscription set state to CONFIGURED upon successful acquisition.

Usage Examples

Initial Config Fetch and Polling Loop

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

using namespace config;

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

// Blocking initial fetch -- freezes subscription set
if (subscriber.nextConfig()) {
    auto cfg = handle->getConfig();
    // Apply initial configuration
}

// Continuous polling loop
while (!subscriber.isClosed()) {
    if (subscriber.nextConfig(60s)) {
        if (handle->isChanged()) {
            auto cfg = handle->getConfig();
            // React to config change
        }
    }
}

Non-Blocking Poll

// Check for config changes without blocking
if (subscriber.nextConfigNow()) {
    auto cfg = handle->getConfig();
    // Process updated config
}

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment