global-configuration.rst

.. default-domain:: 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`.

// 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::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.