.. _global-configuration: .. default-domain:: cpp .. highlight:: cpp

==================== Global Configuration

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.

Reading data

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.

.. function:: template<class T> const 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.

.. code-block:: cpp

  auto& config = GlobalConfig::globalConfig();
  double value = config.get<double>("path/to/key", 1.0);

.. function:: const Reference<ConfigValue> get(KeyRef name)

Returns the value associated with name stored in global configuration.

.. code-block:: cpp

  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);

.. function:: const std::map<KeyRef, Reference<ConfigValue>> get(KeyRangeRef range)

Returns all values in the specified range.

.. type:: ConfigValue

Holds a global configuration value and the arena where it lives. ::

 struct ConfigValue : ReferenceCounted<ConfigValue> {
    Arena arena;
    std::any value;
 }

arena The arena where the value (and the associated key) lives in memory.

value The stored value.

Writing data

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 :ref:api-python-tuple-layer.

.. code-block:: cpp

// In GlobalConfig.actor.h extern const KeyRef myGlobalConfigKey; // In GlobalConfig.actor.cpp const KeyRef myGlobalConfigKey = "config/key"_sr;

// When you want to set the value.. Tuple value = Tuple::makeTuple((double)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.

^^^^^^^^^^^^^ Clearing data ^^^^^^^^^^^^^

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.

Watching data

Global configuration provides functionality to watch for changes.

.. function:: Future<Void> onInitialized()

Returns a Future which will be triggered when global configuration has been successfully initialized and populated with data.

.. function:: Future<Void> onChange()

Returns a Future which will be triggered when any key-value pair in global configuration changes.

.. function:: void trigger(KeyRef key, std::function<void(std::optionalstd::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.