Principle:Vespa engine Vespa Change Polling Loop
| Metadata | |
|---|---|
| Sources | Vespa |
| Domains | Configuration, Distributed_Systems |
| Last Updated | 2026-02-09 12:00 GMT |
Overview
The change polling loop is a continuous monitoring pattern where processes repeatedly check for configuration updates, enabling hot-reconfiguration without restart through generation-based change detection.
Description
After initial configuration has been fetched and applied, Vespa processes enter a change polling loop to monitor for configuration updates. This loop repeatedly calls nextGeneration() (or nextConfig()) to detect when the config server has published a new configuration generation.
The key distinction between the two polling methods is:
nextConfig()returnstrueonly when at least one subscribed config has changed content in the new generationnextGeneration()returnstrueon any new generation, even if no content has changed
The nextGeneration() method is preferred when the process needs to be aware of generation changes for coordination purposes, even when its own configuration has not changed. For example, a search node might need to acknowledge a new generation to the cluster controller even if only other nodes' configurations changed.
The polling loop is combined with ConfigHandle::isChanged() to achieve efficient selective reconfiguration:
nextGeneration()detects that a new generation is available- For each handle,
isChanged()indicates whether that specific config changed - Only components whose config actually changed need to be reconfigured
This pattern enables hot-reconfiguration -- the ability to update a running process's configuration without stopping and restarting it. Hot-reconfiguration is essential in Vespa's distributed architecture where hundreds of processes may need to be reconfigured atomically when an application package is deployed.
Usage
Use this principle in the main operational loop of any long-running Vespa process that needs to react to configuration changes. The polling loop typically runs in a dedicated thread or as part of the process's event loop.
Common patterns include:
- A search backend polling for rank profile changes
- A document processor polling for schema changes
- A container process polling for application reconfiguration
- Any process that needs generation awareness for cluster coordination
Theoretical Basis
The change polling loop implements a pull-based change detection model, as opposed to push-based notification. In this model:
- The client periodically queries the server: "Has anything changed since generation g?"
The server responds with either:
- The same generation (no change)
- A new generation with updated config payloads
This is fundamentally different from a push model (where the server notifies the client) and has the following trade-offs:
Advantages of pull-based:
- The client controls the rate of change application
- No persistent server-to-client connections required for notifications
- Simpler failure semantics: a missed poll simply results in a delayed update, not a lost update
- Natural rate limiting: the client processes one generation at a time
Generation semantics:
A generation is a monotonically increasing identifier (64-bit integer) assigned to each configuration deployment. When an application package is deployed, the config server assigns a new generation number to the entire configuration set.
- gn+1 > gn for successive generations
The relationship between generation change and content change can be expressed as:
- content_changed(Ci) implies generation_changed(Ci)
- generation_changed(Ci) does NOT imply content_changed(Ci)
A generation change without content change occurs when other configs in the same application change but the specific subscribed config remains the same.