SST  13.0.0
StructuralSimulationToolkit
SST::Params Class Reference

Parameter store. More...

#include <params.h>

Inheritance diagram for SST::Params:
SST::Core::Serialization::serializable

Public Types

typedef std::string key_type
 
typedef std::set< key_type, KeyCompare > KeySet_t
 

Public Member Functions

bool enableVerify (bool enable)
 Enable or disable parameter verification on an instance of Params. More...
 
size_t size () const
 Returns the size of the Params. More...
 
bool empty () const
 Returns true if the Params is empty. More...
 
 Params ()
 Create a new, empty Params.
 
 Params (const Params &old)
 Create a copy of a Params object.
 
Paramsoperator= (const Params &old)
 Assignment operator. More...
 
void clear ()
 Erases all elements, including deleting reference to global param sets.
 
size_t count (const key_type &k) const
 Finds the number of elements with given key. More...
 
template<class T >
std::enable_if< not std::is_same< std::string, T >::value, T >::type find (const std::string &k, T default_value, bool &found) const
 Find a Parameter value in the set, and return its value as a type T. More...
 
template<class T >
find (const std::string &k, const std::string &default_value, bool &found) const
 Find a Parameter value in the set, and return its value as a type T. More...
 
template<class T >
std::enable_if< std::is_same< bool, T >::value, T >::type find (const std::string &k, const char *default_value, bool &found) const
 Find a Parameter value in the set, and return its value as a type T. More...
 
template<class T >
find (const std::string &k, T default_value) const
 Find a Parameter value in the set, and return its value as a type T. More...
 
template<class T >
find (const std::string &k, const std::string &default_value) const
 Find a Parameter value in the set, and return its value as a type T. More...
 
template<class T >
std::enable_if< std::is_same< bool, T >::value, T >::type find (const std::string &k, const char *default_value) const
 Find a Parameter value in the set, and return its value as a type T. More...
 
template<class T >
find (const std::string &k) const
 Find a Parameter value in the set, and return its value as a type T. More...
 
template<class T >
std::enable_if< not std::is_same< bool, T >::value, T >::type find (const std::string &k, bool &found) const
 Find a Parameter value in the set, and return its value as a type T. More...
 
template<class T >
void find_array (const key_type &k, std::vector< T > &vec) const
 Find a Parameter value in the set, and return its value as a vector of T's. More...
 
template<class T >
void find_set (const key_type &k, std::set< T > &set) const
 Find a Parameter value in the set, and return its value as a set of T's. More...
 
template<class keyT , class valT >
void find_map (const key_type &k, std::map< keyT, valT > &map) const
 Find a Parameter value in the set, and return its value as a map<keyT,valT>. More...
 
bool is_value_array (const key_type &k) const
 Checks to see if the value associated with the given key is considered to be an array. More...
 
void print_all_params (std::ostream &os, const std::string &prefix="") const
 Print all key/value parameter pairs to specified ostream.
 
void print_all_params (Output &out, const std::string &prefix="") const
 Print all key/value parameter pairs to specified ostream.
 
void insert (const std::string &key, const std::string &value, bool overwrite=true)
 Add a key/value pair into the param object. More...
 
void insert (const Params &params)
 Add contents of input Params object to current Params object. More...
 
std::set< std::string > getKeys () const
 Get all the keys contained in the Params object. More...
 
Params get_scoped_params (const std::string &scope) const
 Returns a new parameter object with parameters that match the specified scoped prefix (scopes are separated with "." The keys will be stripped of the "scope." prefix. More...
 
bool contains (const key_type &k) const
 Search the container for a particular key. More...
 
void pushAllowedKeys (const KeySet_t &keys)
 
void popAllowedKeys ()
 Removes the most recent set of keys considered allowed.
 
void serialize_order (SST::Core::Serialization::serializer &ser) override
 
void verifyParam (const key_type &k) const
 
void addGlobalParamSet (const std::string &set)
 Adds a global param set to be looked at in this Params object if the key isn't found locally. More...
 
std::vector< std::string > getLocalKeys () const
 Get a vector of the local keys. More...
 
std::vector< std::string > getSubscribedGlobalParamSets () const
 Get a vector of the global param sets this Params object is subscribed to. More...
 
void verifyKey (const key_type &k) const
 
friend int ::main (int argc, char *argv[])
 
- Public Member Functions inherited from SST::Core::Serialization::serializable
virtual const char * cls_name () const =0
 
virtual uint32_t cls_id () const =0
 
virtual std::string serialization_name () const =0
 

Static Public Member Functions

static void enableVerify ()
 Enable, on a global scale, parameter verification. More...
 
static void insert_global (const std::string &set, const key_type &key, const key_type &value, bool overwrite=true)
 Adds a key/value pair to the specified global set. More...
 
static std::map< std::string, std::string > getGlobalParamSet (const std::string &name)
 Get a named global parameter set. More...
 
static std::vector< std::string > getGlobalParamSetNames ()
 Get a vector of the names of available global parameter sets. More...
 
static uint32_t getKey (const std::string &str)
 
static const std::string & getParamName (uint32_t id)
 Given a Parameter Key ID, return the Name of the matching parameter. More...
 

Data Fields

std::map< uint32_t, std::string > my_data
 
std::vector< std::map< uint32_t, std::string > * > data
 
std::vector< KeySet_tallowedKeys
 
bool verify_enabled
 

Static Public Attributes

static bool g_verify_enabled = false
 
static std::map< std::string, uint32_t > keyMap
 
static std::vector< std::string > keyMapReverse
 
static SST::Core::ThreadSafe::Spinlock keyLock
 
static SST::Core::ThreadSafe::Spinlock globalLock
 
static uint32_t nextKeyID = 1
 
static std::map< std::string, std::map< uint32_t, std::string > > global_params
 
- Static Public Attributes inherited from SST::Core::Serialization::serializable
static constexpr uint32_t NullClsId = std::numeric_limits<uint32_t>::max()
 

Friends

class SST::Core::ConfigGraphOutput
 
class SST::SSTModelDescription
 

Additional Inherited Members

- Protected Types inherited from SST::Core::Serialization::serializable
enum  cxn_flag_t { ConstructorFlag }
 
- Static Protected Member Functions inherited from SST::Core::Serialization::serializable
static void serializable_abort (uint32_t line, const char *file, const char *func, const char *obj)
 

Detailed Description

Parameter store.

Stores key-value pairs as std::strings and provides a templated find method for finding values and converting them to arbitrary types (

See also
find()).

NOTE: Params objects should only be used for simulation initialization, a Params object should not be used as part of an event, as serialization of Params objects only works correctly as part of ConfigGraph serialization.

Member Typedef Documentation

◆ key_type

typedef std::string SST::Params::key_type

Type of key (string)

◆ KeySet_t

typedef std::set<key_type, KeyCompare> SST::Params::KeySet_t

Type of a set of keys

Member Function Documentation

◆ addGlobalParamSet()

void SST::Params::addGlobalParamSet ( const std::string &  set)

Adds a global param set to be looked at in this Params object if the key isn't found locally.

It will search the global sets in the order they were inserted and return immediately after finding the key in one of the sets.

Parameters
setset to add to the search list for this object

◆ contains()

bool SST::Params::contains ( const key_type k) const

Search the container for a particular key.

This will search both local and global params.

Parameters
kKey to search for
Returns
True if the params contains the key, false otherwise

◆ count()

size_t SST::Params::count ( const key_type k) const

Finds the number of elements with given key.

The call will check both local and global params, but will still only report one instance if the given key is found in both the local and global param sets.

Parameters
kKey of (key, value) pairs to be located.
Returns
Number of elements with specified key (either 1 or 0).

◆ empty()

bool SST::Params::empty ( ) const

Returns true if the Params is empty.

Checks both local and global param sets.

Returns
true if this Params object is empty, false otherwise

References getKeys().

◆ enableVerify() [1/2]

bool SST::Params::enableVerify ( bool  enable)
inline

Enable or disable parameter verification on an instance of Params.

Useful when generating a new set of Params to pass off to a module.

Returns
returns the previous state of the flag

Referenced by get_scoped_params().

◆ enableVerify() [2/2]

static void SST::Params::enableVerify ( )
inlinestatic

Enable, on a global scale, parameter verification.

Used after construction of the config graph so that warnings are not generated during construction.

◆ find() [1/8]

template<class T >
std::enable_if<not std::is_same<std::string, T>::value, T>::type SST::Params::find ( const std::string &  k,
default_value,
bool &  found 
) const
inline

Find a Parameter value in the set, and return its value as a type T.

Type T must be either a basic numeric type (including bool) , a std::string, or a class that has a constructor with a std::string as its only parameter. This class uses SST::Core::from_string to do the conversion.

Parameters
k- Parameter name
default_value- Default value to return if parameter isn't found
found- set to true if the the parameter was found
Exceptions
std::invalid_argumentIf value in (key, value) can't be converted to type T, an invalid_argument exception is thrown.

Referenced by SST::Statistics::StatisticOutputTextBase::checkOutputParameters(), SST::Statistics::StatisticOutputJSON::checkOutputParameters(), SST::Statistics::StatisticOutputCSV::checkOutputParameters(), and SST::Statistics::StatisticBase::StatisticBase().

◆ find() [2/8]

template<class T >
T SST::Params::find ( const std::string &  k,
const std::string &  default_value,
bool &  found 
) const
inline

Find a Parameter value in the set, and return its value as a type T.

Type T must be either a basic numeric type (including bool) , a std::string, or a class that has a constructor with a std::string as its only parameter. This class uses SST::Core::from_string to do the conversion.

Parameters
k- Parameter name
default_value- Default value to return if parameter isn't found, specified as a string
found- set to true if the the parameter was found

◆ find() [3/8]

template<class T >
std::enable_if<std::is_same<bool, T>::value, T>::type SST::Params::find ( const std::string &  k,
const char *  default_value,
bool &  found 
) const
inline

Find a Parameter value in the set, and return its value as a type T.

This version of find is only enabled for bool. This is required because a string literal will be preferentially cast to a bool rather than a string. This ensures that find<bool> works correctly for string literals. This class uses SST::Core::from_string to do the conversion.

Parameters
k- Parameter name
default_value- Default value to return if parameter isn't found, specified as a string literal

◆ find() [4/8]

template<class T >
T SST::Params::find ( const std::string &  k,
default_value 
) const
inline

Find a Parameter value in the set, and return its value as a type T.

Type T must be either a basic numeric type (including bool), a std::string, or a class that has a constructor with a std::string as its only parameter. This class uses SST::Core::from_string to do the conversion.

Parameters
k- Parameter name
default_value- Default value to return if parameter isn't found

◆ find() [5/8]

template<class T >
T SST::Params::find ( const std::string &  k,
const std::string &  default_value 
) const
inline

Find a Parameter value in the set, and return its value as a type T.

Type T must be either a basic numeric type (including bool) , a std::string, or a class that has a constructor with a std::string as its only parameter. This class uses SST::Core::from_string to do the conversion.

Parameters
k- Parameter name
default_value- Default value to return if parameter isn't found, specified as a string

◆ find() [6/8]

template<class T >
std::enable_if<std::is_same<bool, T>::value, T>::type SST::Params::find ( const std::string &  k,
const char *  default_value 
) const
inline

Find a Parameter value in the set, and return its value as a type T.

This version of find is only enabled for bool. This is required because a string literal will be preferentially cast to a bool rather than a string. This ensures that find<bool> works correctly for string literals.This class uses SST::Core::from_string to do the conversion.

Parameters
k- Parameter name
default_value- Default value to return if parameter isn't found, specified as a string literal

◆ find() [7/8]

template<class T >
T SST::Params::find ( const std::string &  k) const
inline

Find a Parameter value in the set, and return its value as a type T.

Type T must be either a basic numeric type (including bool) , a std::string, or a class that has a constructor with a std::string as its only parameter. This class uses SST::Core::from_string to do the conversion.

Parameters
k- Parameter name

◆ find() [8/8]

template<class T >
std::enable_if<not std::is_same<bool, T>::value, T>::type SST::Params::find ( const std::string &  k,
bool &  found 
) const
inline

Find a Parameter value in the set, and return its value as a type T.

Type T must be either a basic numeric type , a std::string, or a class that has a constructor with a std::string as its only parameter. This version of find is not enabled for bool as it conflicts with find<bool>(string key, bool default_value). This class uses SST::Core::from_string to do the conversion.

Parameters
k- Parameter name
found- set to true if the the parameter was found

◆ find_array()

template<class T >
void SST::Params::find_array ( const key_type k,
std::vector< T > &  vec 
) const
inline

Find a Parameter value in the set, and return its value as a vector of T's.

The array will be appended to the end of the vector.

Type T must be either a basic numeric type (including bool) , a std::string, or a class that has a constructor with a std::string as its only parameter. This class uses SST::Core::from_string to do the conversion. The values in the array must be enclosed in square brackets ( [] ), and be comma separated (commas in double or single quotes will not be considered a delimiter). If there are no square brackets, the entire string will be considered one value and a single item will be added to the vector.

More details about parsing the values out of the string:

Parses a string representing an array of tokens. It is tailored to the types strings you get when passing a python list as the param string. When you call addParam() on a python list in the input file, it will call the str() function on the list, which creates a string with the following format: [item1, item2, item3]

The format of the items depends on where they came from. The string for the items are generated by calling the repr() function on them. For strings, this means they will typically be enclosed in single quotes. It is possible that they end up enclosed in double quotes if the string itself contains a single quote. For strings which contain both single and double quotes, the repr() will create a single quoted string with all internal single quotes escaped with '\'. Most other items used in SST do not enclose the string in quotes, though any string that contains a comma would need to be enclosed in quotes, since the comma is the delimiter character used. This is not done automatically, so if you have something that generates a commma in the string created by repr(), you may need to create an array string manually. Also, any string that starts with a quote character, must end with the same quote character.

Tokens are generated by splitting the string on commas that are not within quotes (double or single). All whitespace at the beginning and end of a token is ignored (unless inside quotes). Once the tokens are generated, any quoted string will have the front and back quotes removed. The '\' for any escaped quote of the same type as the front and back is also removed.

Examples:

These will produce the same results: [1, 2, 3, 4, 5] ['1', '2', '3', '4', '5']

Examples of strings using double and/or single quotes: 'This is "a" test' -> This is "a" test "This is 'a' test" -> This is 'a' test 'This "is \'a\'" test' -> This "is 'a'" test 'This "is \"a"" test' -> This "is "a"" test

Parameters
k- Parameter name
vec- vector to append array items to

References verifyKey().

◆ find_map()

template<class keyT , class valT >
void SST::Params::find_map ( const key_type k,
std::map< keyT, valT > &  map 
) const
inline

Find a Parameter value in the set, and return its value as a map<keyT,valT>.

The items will be added to the passed in map.

Types keyT and valT must be either a basic numeric type (including bool), a std::string, or a class that has a constructor with a std::string as its only parameter. This class uses SST::Core::from_string to do the conversion. The values in the map must be enclosed in curly braces ( {} ), the key/value pairs must be comma separated (commas in double or single quotes will not be considered a delimiter) and the key and value in the pairs must be separated by a colon (colons in double or single quotes will not be considered a delimiter). If there are no curly braces, the function will throw an std::invalid_argument exception without adding anything to the map.

More details about parsing the values out of the string:

Parses a string representing a set of tokens. It is tailored to the types strings you get when passing a python set as the param string. When you call addParam() on a python set in the input file, it will call the str() function on the set, which creates a string with the following format: {key1 : value1, key2 : value2, key3 : value3}

The format of each item depends on where it came from. The string for the items are generated by calling the repr() function on them. For strings, this means they will typically be enclosed in single quotes. It is possible that they end up enclosed in double quotes if the string itself contains a single quote. For strings which contain both single and double quotes, the repr() will create a single quoted string with all internal single quotes escaped with '\'. Most other items used in SST do not enclose the string in quotes, though any string that contains a comma would need to be enclosed in quotes, since the comma is the delimiter character used. This is not done automatically, so if you have something that generates a commma in the string created by repr(), you may need to create an array string manually. Also, any string that starts with a quote character, must end with the same quote character.

Tokens are generated by splitting the string on commas that are not within quotes (double or single). All whitespace at the beginning and end of a token is ignored (unless inside quotes). Once the tokens are generated, any quoted string will have the front and back quotes removed. The '\' for any escaped quote of the same type as the front and back is also removed.

Examples:

These will produce the same results: {"one" : 1, "two" : 2, "three" : 3, "Four" : 4} {"one" :'1', "two" : '2', "three" : '3', "four" : '4'}

Examples of strings using double and/or single quotes: 'This is "a" test' -> This is "a" test "This is 'a' test" -> This is 'a' test 'This "is \'a\'" test' -> This "is 'a'" test 'This "is \"a"" test' -> This "is "a"" test

Parameters
k- Parameter name
map- map to add items to (new items will overwrite old items)

References verifyKey().

◆ find_set()

template<class T >
void SST::Params::find_set ( const key_type k,
std::set< T > &  set 
) const
inline

Find a Parameter value in the set, and return its value as a set of T's.

The items will be added to the passed in set.

Type T must be either a basic numeric type (including bool), a std::string, or a class that has a constructor with a std::string as its only parameter. This class uses SST::Core::from_string to do the conversion. The values in the set must be enclosed in curly braces ( {} ), and be comma separated (commas in double or single quotes will not be considered a delimiter). If there are no curly braces, the entire string will be considered one value and a single item will be added to the set.

More details about parsing the values out of the string:

Parses a string representing a set of tokens. It is tailored to the types strings you get when passing a python set as the param string. When you call addParam() on a python set in the input file, it will call the str() function on the set, which creates a string with the following format: {item1, item2, item3}

The format of the items depends on where they came from. The string for the items are generated by calling the repr() function on them. For strings, this means they will typically be enclosed in single quotes. It is possible that they end up enclosed in double quotes if the string itself contains a single quote. For strings which contain both single and double quotes, the repr() will create a single quoted string with all internal single quotes escaped with '\'. Most other items used in SST do not enclose the string in quotes, though any string that contains a comma would need to be enclosed in quotes, since the comma is the delimiter character used. This is not done automatically, so if you have something that generates a commma in the string created by repr(), you may need to create an array string manually. Also, any string that starts with a quote character, must end with the same quote character.

Tokens are generated by splitting the string on commas that are not within quotes (double or single). All whitespace at the beginning and end of a token is ignored (unless inside quotes). Once the tokens are generated, any quoted string will have the front and back quotes removed. The '\' for any escaped quote of the same type as the front and back is also removed.

Examples:

These will produce the same results: {1, 2, 3, 4, 5} {'1', '2', '3', '4', '5'}

Examples of strings using double and/or single quotes: 'This is "a" test' -> This is "a" test "This is 'a' test" -> This is 'a' test 'This "is \'a\'" test' -> This "is 'a'" test 'This "is \"a"" test' -> This "is "a"" test

Parameters
k- Parameter name
set- set to add items to (new items will overwrite old items)

References verifyKey().

◆ get_scoped_params()

Params SST::Params::get_scoped_params ( const std::string &  scope) const

Returns a new parameter object with parameters that match the specified scoped prefix (scopes are separated with "." The keys will be stripped of the "scope." prefix.

Function will search both local and global params, but all params will be copied into the local space of the new Params object.

Parameters
scopeScope to search (anything prefixed with "scope." will be included in the return Params object
Returns
New Params object with the found scoped params.

References enableVerify(), and insert().

◆ getGlobalParamSet()

std::map< std::string, std::string > SST::Params::getGlobalParamSet ( const std::string &  name)
static

Get a named global parameter set.

Parameters
nameName of the set to get
Returns
returns a copy of the reqeusted global param set

References getParamName().

Referenced by SST::Core::ConfigGraphOutput::getGlobalParamSet().

◆ getGlobalParamSetNames()

std::vector< std::string > SST::Params::getGlobalParamSetNames ( )
static

Get a vector of the names of available global parameter sets.

Returns
returns a vector of the names of available global param sets

Referenced by SST::Core::ConfigGraphOutput::getGlobalParamSetNames().

◆ getKeys()

std::set< std::string > SST::Params::getKeys ( ) const

Get all the keys contained in the Params object.

This will give both local and global params.

Referenced by empty(), and size().

◆ getLocalKeys()

std::vector< std::string > SST::Params::getLocalKeys ( ) const

Get a vector of the local keys.

Returns
returns a vector of the local keys in this Params object

References getParamName(), and size().

Referenced by SST::Core::ConfigGraphOutput::getParamsLocalKeys().

◆ getParamName()

const std::string & SST::Params::getParamName ( uint32_t  id)
static

Given a Parameter Key ID, return the Name of the matching parameter.

Parameters
idKey ID to look up
Returns
String name of the parameter

Referenced by getGlobalParamSet(), and getLocalKeys().

◆ getSubscribedGlobalParamSets()

std::vector< std::string > SST::Params::getSubscribedGlobalParamSets ( ) const

Get a vector of the global param sets this Params object is subscribed to.

Returns
returns a vector of the global param sets his Params object is subscribed to

Referenced by SST::Core::ConfigGraphOutput::getSubscribedGlobalParamSets().

◆ insert() [1/2]

void SST::Params::insert ( const std::string &  key,
const std::string &  value,
bool  overwrite = true 
)

Add a key/value pair into the param object.

Parameters
keykey to add to the map
valuevalue to add to the map
overwritecontrols whether the key/value pair will overwrite an existing pair in the set

Referenced by SST::ConfigGraph::addStatisticOutputParameter(), get_scoped_params(), and SST::Simulation_impl::intializeProfileTools().

◆ insert() [2/2]

void SST::Params::insert ( const Params params)

Add contents of input Params object to current Params object.

This will also add any pointers to global param sets after the existing pointers to global param sets in this object.

Parameters
paramsParams object that should added to current object

◆ insert_global()

void SST::Params::insert_global ( const std::string &  set,
const key_type key,
const key_type value,
bool  overwrite = true 
)
static

Adds a key/value pair to the specified global set.

Parameters
setglobal set to add the key/value pair to
keykey to add to the map
valuevalue to add to the map
overwritecontrols whether the key/value pair will overwrite an existing pair in the set

◆ is_value_array()

bool SST::Params::is_value_array ( const key_type k) const
inline

Checks to see if the value associated with the given key is considered to be an array.

A value is considered to be an array if it is enclosed in square brackets ([]). No whitespace before or after the brackets is allowed.

Parameters
k- Parameter name
Returns
true if value is an array as described above, false otherwise.

◆ operator=()

Params & SST::Params::operator= ( const Params old)

Assignment operator.

Parameters
oldParam to be copied

All the elements of old are copied, This will also copy over any references to global param sets

◆ pushAllowedKeys()

void SST::Params::pushAllowedKeys ( const KeySet_t keys)
Parameters
keysSet of keys to consider valid to add to the stack of legal keys

Referenced by SST::Factory::CreateComponent(), and SST::Factory::CreateWithParams().

◆ size()

size_t SST::Params::size ( ) const

Returns the size of the Params.

This will count both local and global params.

Returns
number of key/value pairs in this Params object

References getKeys().

Referenced by getLocalKeys().

◆ verifyKey()

void SST::Params::verifyKey ( const key_type k) const
Parameters
kKey to check for validity
Returns
True if the key is considered allowed

References SST::Output::output(), and SST::Output::STDERR.

Referenced by find_array(), find_map(), find_set(), and verifyParam().

◆ verifyParam()

void SST::Params::verifyParam ( const key_type k) const
Parameters
kKey to check for validity
Returns
True if the key is considered allowed

References verifyKey().


The documentation for this class was generated from the following files: