Manages configuration options for RapidsMPF operations. More...
#include <config.hpp>
Public Member Functions | |
| Options (std::unordered_map< std::string, OptionValue > options={}) | |
Constructs an Options instance from option values. More... | |
| Options (std::unordered_map< std::string, std::string > options_as_strings) | |
Constructs an Options instance from option values as strings. More... | |
| bool | insert_if_absent (std::string const &key, std::string_view option_as_string) |
| Inserts an option only if it is not already present. More... | |
| std::size_t | insert_if_absent (std::unordered_map< std::string, std::string > options_as_strings) |
| Inserts multiple options if they are not already present. More... | |
| template<typename T > | |
| bool | insert_if_absent (std::string const &key, T value) requires(!std |
| Inserts an option only if it is not already present. More... | |
| template<typename T > | |
| T const & | get (std::string const &key, OptionFactory< T > factory) |
| Retrieves a configuration option by key. More... | |
| std::unordered_map< std::string, std::string > | get_strings () const |
| Retrieves all option values as strings. More... | |
| std::vector< std::uint8_t > | serialize () const |
| Serializes the options into a binary buffer. More... | |
Static Public Member Functions | |
| static Options | deserialize (std::vector< std::uint8_t > const &buffer) |
| Deserializes a binary buffer into an Options object. More... | |
Manages configuration options for RapidsMPF operations.
The Options class provides a high-level interface for storing and retrieving configuration options.
All keys are trimmed and converted to lower case using rapidsmpf::trim() and rapidsmpf::to_lower().
rapidsmpf::config::Options is efficient as it uses a shared pointer to the shared options (OptionsShared). Definition at line 140 of file config.hpp.
| rapidsmpf::config::Options::Options | ( | std::unordered_map< std::string, OptionValue > | options = {} | ) |
Constructs an Options instance from option values.
| options | A map of option keys to their corresponding option value. |
| std::invalid_argument | If keys are not case-insensitive. |
| rapidsmpf::config::Options::Options | ( | std::unordered_map< std::string, std::string > | options_as_strings | ) |
Constructs an Options instance from option values as strings.
| options_as_strings | A map of option keys to their string representations. |
| std::invalid_argument | If keys are not case-insensitive. |
|
static |
Deserializes a binary buffer into an Options object.
See Options::serialize() for the binary format.
| buffer | The binary buffer produced by Options::serialize(). |
| std::invalid_argument | If the buffer is malformed or incomplete. |
| std::out_of_range | If offsets exceed buffer boundaries. |
|
inline |
Retrieves a configuration option by key.
If the option is not present, it will be constructed using the provided factory, which receives the string representation of the option (or an empty string if unset).
| T | The type of the option to retrieve. |
| key | The option key (should be lower case). |
| factory | Function to construct the option from a string. |
| std::invalid_argument | If the stored option type does not match T. |
| std::bad_any_cast | If T doesn't match the type of the option. |
T, subsequent calls to get on the same key must use the same T. Using a different T for the same key will result in a std::bad_any_cast. Definition at line 245 of file config.hpp.
| std::unordered_map<std::string, std::string> rapidsmpf::config::Options::get_strings | ( | ) | const |
Retrieves all option values as strings.
This method returns a map of all currently stored options where both the keys and values are represented as strings.
Options that do not have a string representation, such as those inserted using insert_if_absent<T>(), are included with an empty string value.
| bool rapidsmpf::config::Options::insert_if_absent | ( | std::string const & | key, |
| std::string_view | option_as_string | ||
| ) |
Inserts an option only if it is not already present.
This method checks whether the given option key exists in the current set of options. If it does not, the option is inserted in its string representation.
| key | The option key to insert. The key is trimmed and converted to lower case before insertion. |
| option_as_string | The string representation of the option value. |
true if the option was inserted; false if it was already present.
|
inline |
Inserts an option only if it is not already present.
This method stores a typed value directly, bypassing the string-based representation used for lazy parsing. Once inserted, the option is initialized, and subsequent calls to get<T>() for the same key must use the same T.
This method is only enabled for non string-like types. Values convertible to std::string_view (for example std::string, std::string_view, or string literals) are handled by the string-based overloads instead.
Because no string representation is stored, inserting an option using this method makes the Options instance unserializable. This is consistent with the behavior of get(), as serialization relies exclusively on the original string representations of options.
| T | Type of the value to store. |
| key | The option key to insert. The key is trimmed and converted to lower case before insertion. |
| value | The value to store. |
true if the option was inserted; false if it was already present. Definition at line 215 of file config.hpp.
| std::size_t rapidsmpf::config::Options::insert_if_absent | ( | std::unordered_map< std::string, std::string > | options_as_strings | ) |
Inserts multiple options if they are not already present.
This method attempts to insert each option key-value pair from the provided map into the current set of options. Each insertion is performed only if the key does not already exist in the options.
| options_as_strings | A map of option keys to their string representations. |
| std::vector<std::uint8_t> rapidsmpf::config::Options::serialize | ( | ) | const |
Serializes the options into a binary buffer.
An Options instance can only be serialized if all options are still represented exclusively by their original string values. Serialization is based on these string representations and cannot reflect options that have been accessed, parsed, or initialized with typed values.
As a result, serialization is disallowed if any option has been accessed via get() or inserted using the typed insert_if_absent<T>() method, since their string values may no longer accurately reflect their state.
The format (v1) is:
Offsets are absolute byte positions into the buffer.
Serialization limits:
| std::invalid_argument | If any option has already been accessed or inserted as a typed value. |
1.9.1