mirror of
https://github.com/apple/foundationdb.git
synced 2025-05-14 01:42:37 +08:00
131 lines
4.4 KiB
ReStructuredText
131 lines
4.4 KiB
ReStructuredText
.. _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 = 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.
|
|
|
|
^^^^^^^^^^^^^
|
|
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.
|