From 2150257c1dfb9da528f111c1f499157dec46cc60 Mon Sep 17 00:00:00 2001 From: Alexey Rybalchenko Date: Thu, 11 Jul 2019 17:56:58 +0200 Subject: [PATCH] Extend configuration docs --- docs/Configuration.md | 32 +++++++++++++++- fairmq/PluginServices.h | 81 +++++++++++++++++++++++++++-------------- fairmq/ProgOptions.h | 68 ++++++++++++++++++++++++++++++++++ 3 files changed, 152 insertions(+), 29 deletions(-) diff --git a/docs/Configuration.md b/docs/Configuration.md index 68ce874e..e2e0bf2f 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -4,7 +4,37 @@ ## 3.1 Device Configuration -Devices receive configuration primarily via provided command line options (that can be extended per device). +Device Configuration is stored in configuration object - `fair::mq::ProgOptions`. It is accessible by the device, plugins or from DeviceRunner/main: + +Plugins <---read/write---> ProgOptions <---read/write---> Device + +Whenever a configuration property is set, it is set in ProgOptions. Device/Channels/User code read this value and apply it as necessary at different stages: + - apply it immidiately + - apply it in device/channels during InitializingDevice/Binding/Connecting states + +Here is an overview of the device/channel options and when they are applied: + +| Property | Applied in | +| --- | --- | +| `severity` | immidiately (if `fair::mq::DeviceRunner` is used (also the case when using ``)) | +| `file-severity` | immidiately (if `fair::mq::DeviceRunner` is used (also the case when using ``)) | +| `verbosity` | immidiately (if `fair::mq::DeviceRunner` is used (also the case when using ``)) | +| `color` | immidiately (if `fair::mq::DeviceRunner` is used (also the case when using ``)) | +| `log-to-file` | immidiately (if `fair::mq::DeviceRunner` is used (also the case when using ``)) | +| `id` | at the end of `fair::mq::State::InitializingDevice` | +| `io-threads` | at the end of `fair::mq::State::InitializingDevice` | +| `transport` | at the end of `fair::mq::State::InitializingDevice` | +| `network-interface` | at the end of `fair::mq::State::InitializingDevice` | +| `init-timeout` | at the end of `fair::mq::State::InitializingDevice` | +| `max-run-time` | at the end of `fair::mq::State::InitializingDevice` | +| `shm-segment-size` | at the end of `fair::mq::State::InitializingDevice` | +| `shm-monitor` | at the end of `fair::mq::State::InitializingDevice` | +| `ofi-size-hint` | at the end of `fair::mq::State::InitializingDevice` | +| `rate` | at the end of `fair::mq::State::InitializingDevice` | +| `session` | at the end of `fair::mq::State::InitializingDevice` | +| `chan.*` | at the end of `fair::mq::State::InitializingDevice` (channel addresses can be also applied during `fair::mq::State::Binding`/`fair::mq::State::Connecting`) | + +## 3.2 Configuration options ## 3.2 Communication Channels Configuration diff --git a/fairmq/PluginServices.h b/fairmq/PluginServices.h index 1f0b33c4..fda7541a 100644 --- a/fairmq/PluginServices.h +++ b/fairmq/PluginServices.h @@ -179,6 +179,9 @@ class PluginServices // Config API + /// @brief Checks a property with the given key exist in the configuration + /// @param key + /// @return true if it exists, false otherwise auto PropertyExists(const std::string& key) const -> bool { return fConfig.Count(key) > 0; } /// @brief Set config property @@ -188,15 +191,21 @@ class PluginServices /// Setting a config property will store the value in the FairMQ internal config store and notify any subscribers about the update. /// It is property dependent, if the call to this method will have an immediate, delayed or any effect at all. template - auto SetProperty(const std::string& key, T val) -> void - { - fConfig.SetProperty(key, val); - } + auto SetProperty(const std::string& key, T val) -> void { fConfig.SetProperty(key, val); } + /// @brief Set multiple config properties + /// @param props fair::mq::Properties as an alias for std::map, where property is boost::any void SetProperties(const fair::mq::Properties& props) { fConfig.SetProperties(props); } + /// @brief Updates an existing config property (or fails if it doesn't exist) + /// @param key + /// @param val template bool UpdateProperty(const std::string& key, T val) { return fConfig.UpdateProperty(key, val); } + /// @brief Updates multiple existing config properties (or fails of any of then do not exist, leaving property store unchanged) + /// @param props (fair::mq::Properties as an alias for std::map, where property is boost::any) bool UpdateProperties(const fair::mq::Properties& input) { return fConfig.UpdateProperties(input); } + /// @brief Deletes a property with the given key from the config store + /// @param key void DeleteProperty(const std::string& key) { fConfig.DeleteProperty(key); } /// @brief Read config property, throw if no property with this key exists @@ -205,11 +214,12 @@ class PluginServices template auto GetProperty(const std::string& key) const -> T { return fConfig.GetProperty(key); } + /// @brief Read config property, return provided value if no property with this key exists + /// @param key + /// @param ifNotFound value to return if key is not found + /// @return config property template - T GetProperty(const std::string& key, const T& ifNotFound) const - { - return fConfig.GetProperty(key, ifNotFound); - } + T GetProperty(const std::string& key, const T& ifNotFound) const { return fConfig.GetProperty(key, ifNotFound); } /// @brief Read config property as string, throw if no property with this key exists /// @param key @@ -220,28 +230,39 @@ class PluginServices /// the provided type must then be convertible to string via operator<< auto GetPropertyAsString(const std::string& key) const -> std::string { return fConfig.GetPropertyAsString(key); } - auto GetPropertyAsString(const std::string& key, const std::string& ifNotFound) const -> std::string - { - return fConfig.GetPropertyAsString(key, ifNotFound); - } + /// @brief Read config property, return provided value if no property with this key exists + /// @param key + /// @param ifNotFound value to return if key is not found + /// @return config property converted to string + /// + /// Supports conversion to string for a fixed set of types, + /// for custom/unsupported types add them via `fair::mq::PropertyHelper::AddType("optional label")` + /// the provided type must then be convertible to string via operator<< + auto GetPropertyAsString(const std::string& key, const std::string& ifNotFound) const -> std::string { return fConfig.GetPropertyAsString(key, ifNotFound); } - fair::mq::Properties GetProperties(const std::string& q) const - { - return fConfig.GetProperties(q); - } - fair::mq::Properties GetPropertiesStartingWith(const std::string& q) const - { - return fConfig.GetPropertiesStartingWith(q); - } - std::map GetPropertiesAsString(const std::string& q) const - { - return fConfig.GetPropertiesAsString(q); - } - std::map GetPropertiesAsStringStartingWith(const std::string& q) const - { - return fConfig.GetPropertiesAsStringStartingWith(q); - } + /// @brief Read several config properties whose keys match the provided regular expression + /// @param q regex string to match for + /// @return container with properties (fair::mq::Properties as an alias for std::map, where property is boost::any) + fair::mq::Properties GetProperties(const std::string& q) const { return fConfig.GetProperties(q); } + /// @brief Read several config properties whose keys start with the provided string + /// @param q string to match for + /// @return container with properties (fair::mq::Properties as an alias for std::map, where property is boost::any) + /// + /// Typically more performant than GetProperties with regex + fair::mq::Properties GetPropertiesStartingWith(const std::string& q) const { return fConfig.GetPropertiesStartingWith(q); } + /// @brief Read several config properties as string whose keys match the provided regular expression + /// @param q regex string to match for + /// @return container with properties (fair::mq::Properties as an alias for std::map, where property is boost::any) + std::map GetPropertiesAsString(const std::string& q) const { return fConfig.GetPropertiesAsString(q); } + /// @brief Read several config properties as string whose keys start with the provided string + /// @param q string to match for + /// @return container with properties (fair::mq::Properties as an alias for std::map, where property is boost::any) + /// + /// Typically more performant than GetPropertiesAsString with regex + std::map GetPropertiesAsStringStartingWith(const std::string& q) const { return fConfig.GetPropertiesAsStringStartingWith(q); } + /// @brief Retrieve current channel information + /// @return a map of auto GetChannelInfo() const -> std::unordered_map { return fConfig.GetChannelInfo(); } /// @brief Discover the list of property keys @@ -278,9 +299,13 @@ class PluginServices /// @param subscriber auto UnsubscribeFromPropertyChangeAsString(const std::string& subscriber) -> void { fConfig.UnsubscribeAsString(subscriber); } + /// @brief Increases console logging severity, or sets it to lowest if it is already highest auto CycleLogConsoleSeverityUp() -> void { Logger::CycleConsoleSeverityUp(); } + /// @brief Decreases console logging severity, or sets it to highest if it is already lowest auto CycleLogConsoleSeverityDown() -> void { Logger::CycleConsoleSeverityDown(); } + /// @brief Increases logging verbosity, or sets it to lowest if it is already highest auto CycleLogVerbosityUp() -> void { Logger::CycleVerbosityUp(); } + /// @brief Decreases logging verbosity, or sets it to highest if it is already lowest auto CycleLogVerbosityDown() -> void { Logger::CycleVerbosityDown(); } static const std::unordered_map fkDeviceStateStrMap; diff --git a/fairmq/ProgOptions.h b/fairmq/ProgOptions.h index 8987480f..dcc002c2 100644 --- a/fairmq/ProgOptions.h +++ b/fairmq/ProgOptions.h @@ -46,9 +46,16 @@ class ProgOptions void AddToCmdLineOptions(const boost::program_options::options_description optDesc, bool visible = true); boost::program_options::options_description& GetCmdLineOptions(); + /// @brief Checks a property with the given key exist in the configuration + /// @param key + /// @return 1 if it exists, 0 otherwise int Count(const std::string& key) const; + /// @brief Retrieve current channel information + /// @return a map of std::unordered_map GetChannelInfo() const; + /// @brief Discover the list of property keys + /// @return list of property keys std::vector GetPropertyKeys() const; /// @brief Read config property, throw if no property with this key exists @@ -65,6 +72,10 @@ class ProgOptions } } + /// @brief Read config property, return provided value if no property with this key exists + /// @param key + /// @param ifNotFound value to return if key is not found + /// @return config property template T GetProperty(const std::string& key, const T& ifNotFound) const { @@ -83,13 +94,40 @@ class ProgOptions /// for custom/unsupported types add them via `fair::mq::PropertyHelper::AddType("optional label")` /// the provided type must then be convertible to string via operator<< std::string GetPropertyAsString(const std::string& key) const; + /// @brief Read config property, return provided value if no property with this key exists + /// @param key + /// @param ifNotFound value to return if key is not found + /// @return config property converted to string + /// + /// Supports conversion to string for a fixed set of types, + /// for custom/unsupported types add them via `fair::mq::PropertyHelper::AddType("optional label")` + /// the provided type must then be convertible to string via operator<< std::string GetPropertyAsString(const std::string& key, const std::string& ifNotFound) const; + /// @brief Read several config properties whose keys match the provided regular expression + /// @param q regex string to match for + /// @return container with properties (fair::mq::Properties as an alias for std::map, where property is boost::any) fair::mq::Properties GetProperties(const std::string& q) const; + /// @brief Read several config properties whose keys start with the provided string + /// @param q string to match for + /// @return container with properties (fair::mq::Properties as an alias for std::map, where property is boost::any) + /// + /// Typically more performant than GetProperties with regex fair::mq::Properties GetPropertiesStartingWith(const std::string& q) const; + /// @brief Read several config properties as string whose keys match the provided regular expression + /// @param q regex string to match for + /// @return container with properties (fair::mq::Properties as an alias for std::map, where property is boost::any) std::map GetPropertiesAsString(const std::string& q) const; + /// @brief Read several config properties as string whose keys start with the provided string + /// @param q string to match for + /// @return container with properties (fair::mq::Properties as an alias for std::map, where property is boost::any) + /// + /// Typically more performant than GetPropertiesAsString with regex std::map GetPropertiesAsStringStartingWith(const std::string& q) const; + /// @brief Set config property + /// @param key + /// @param val template void SetProperty(const std::string& key, T val) { @@ -103,6 +141,9 @@ class ProgOptions fEvents.Emit(key, GetPropertyAsString(key)); } + /// @brief Updates an existing config property (or fails if it doesn't exist) + /// @param key + /// @param val template bool UpdateProperty(const std::string& key, T val) { @@ -122,12 +163,26 @@ class ProgOptions } } + /// @brief Set multiple config properties + /// @param props fair::mq::Properties as an alias for std::map, where property is boost::any void SetProperties(const fair::mq::Properties& input); + /// @brief Updates multiple existing config properties (or fails of any of then do not exist, leaving property store unchanged) + /// @param props (fair::mq::Properties as an alias for std::map, where property is boost::any) bool UpdateProperties(const fair::mq::Properties& input); + /// @brief Deletes a property with the given key from the config store + /// @param key void DeleteProperty(const std::string& key); + /// @brief Takes the provided channel and creates properties based on it + /// @param name channel name + /// @param channel FairMQChannel reference void AddChannel(const std::string& name, const FairMQChannel& channel); + /// @brief Subscribe to property updates of type T + /// @param subscriber + /// @param callback function + /// + /// Subscribe to property changes with a callback to monitor property changes in an event based fashion. template void Subscribe(const std::string& subscriber, std::function func) const { @@ -137,6 +192,8 @@ class ProgOptions fEvents.Subscribe(subscriber, func); } + /// @brief Unsubscribe from property updates of type T + /// @param subscriber template void Unsubscribe(const std::string& subscriber) const { @@ -144,22 +201,33 @@ class ProgOptions fEvents.Unsubscribe(subscriber); } + /// @brief Subscribe to property updates, with values converted to string + /// @param subscriber + /// @param callback function + /// + /// Subscribe to property changes with a callback to monitor property changes in an event based fashion. Will convert the property to string. void SubscribeAsString(const std::string& subscriber, std::function func) const { std::lock_guard lock(fMtx); fEvents.Subscribe(subscriber, func); } + /// @brief Unsubscribe from property updates that convert to string + /// @param subscriber void UnsubscribeAsString(const std::string& subscriber) const { std::lock_guard lock(fMtx); fEvents.Unsubscribe(subscriber); } + /// @brief prints full options description void PrintHelp() const; + /// @brief prints properties stored in the property container void PrintOptions() const; + /// @brief prints full options description in a compact machine-readable format void PrintOptionsRaw() const; + /// @brief returns the property container const boost::program_options::variables_map& GetVarMap() const { return fVarMap; } /// @brief Read config property, return default-constructed object if key doesn't exist