The global configuration framework is an eventually consistent configuration mechanism to efficiently make runtime changes to all clients and servers. It works by broadcasting updates made to the global configuration key space, relying on individual machines to store existing configuration in-memory.
The global configuration framework provides a key-value interface to all processes and clients in a FoundationDB cluster.
The global configuration framework is internal to FoundationDB and clients will usually have no need to interact with it. The API is provided here for reference.
The global configuration framework is exposed through the
GlobalConfig::globalConfig()
static function. There are separate ways to
read a value, depending on if it is an object or a primitive.
T
>
get
(KeyRef name, T defaultVal)Returns the value associated with name
stored in global configuration,
or defaultVal
if no key matching name
exists. This templated
function is enabled only when the std::is_arithmetic<T>
specialization
returns true.
auto& config = GlobalConfig::globalConfig();
double value = config.get<double>("path/to/key", 1.0);
get
(KeyRef name)Returns the value associated with name
stored in global configuration.
auto& config = GlobalConfig::globalConfig();
auto configValue = config.get("path/to/key");
// Check if value exists
ASSERT(configValue.value.has_value());
// Cast to correct type
auto str = std::any_cast<StringRef>(configValue.value);
get
(KeyRangeRef range)Returns all values in the specified range.
ConfigValue
Holds a global configuration value and the arena where it lives.
struct ConfigValue : ReferenceCounted<ConfigValue> {
Arena arena;
std::any value;
}
arena
value
Writing data to global configuration is done using transactions written to the
special key space range \xff\xff/global_config/ - \xff\xff/global_config/0
.
Values must always be encoded according to the Tuple layer.
// In GlobalConfig.actor.h
extern const KeyRef myGlobalConfigKey;
// In GlobalConfig.actor.cpp
const KeyRef myGlobalConfigKey = LiteralStringRef("config/key");
// When you want to set the value..
Tuple value = Tuple().appendDouble(1.5);
FDBTransaction* tr = ...;
tr->setOption(FDBTransactionOptions::SPECIAL_KEY_SPACE_ENABLE_WRITES);
tr->set(GlobalConfig::prefixedKey(myGlobalConfigKey), value.pack());
// commit transaction
The client is responsible for avoiding conflicts with other global
configuration keys. For most uses, it is recommended to create a new key space.
For example, an application that wants to write configuration data should use
the global_config/config/
namespace, instead of storing keys in the top
level global_config/
key space.
Data can be removed from global configuration using standard transaction semantics. Submit a clear or clear range to the appropriate global configuration keys in the special key space to clear data.
Global configuration provides functionality to watch for changes.
onInitialized
()Returns a Future
which will be triggered when global configuration has
been successfully initialized and populated with data.
onChange
()Returns a Future
which will be triggered when any key-value pair in
global configuration changes.
trigger
(KeyRef key, std::function<void(std::optional<std::any>)> fn)Registers a callback to be called when the value for global configuration
key key
is changed. The callback function takes a single argument, an
optional which will be populated with the updated value when key
is
changed, or an empty optional if the value was cleared. If the value is an
allocated object, its memory remains in control of global configuration.