A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
global-value.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2008 INRIA
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 */
8#ifndef GLOBAL_VALUE_H
9#define GLOBAL_VALUE_H
10
11#include "attribute.h"
12#include "ptr.h"
13
14#include <string>
15#include <vector>
16
17/**
18 * \file
19 * \ingroup core
20 * ns3::GlobalValue declaration.
21 */
22
23namespace ns3
24{
25
26/* Forward declaration */
27namespace tests
28{
29class GlobalValueTestCase;
30}
31
32/**
33 * \ingroup core
34 *
35 * \brief Hold a so-called 'global value'.
36 *
37 * A GlobalValue will get its value from (in order):
38 * - The initial value configured where it is defined,
39 * - From the \c NS_GLOBAL_VALUE environment variable,
40 * - From the command line,
41 * - By explicit call to SetValue() or Bind().
42 *
43 * Instances of this class are expected to be allocated as static
44 * global variables and should be used to store configurable global state.
45 * For example:
46 * \code
47 * // source.cc:
48 * static GlobalValue g_myGlobal =
49 * GlobalValue ("myGlobal", "My global value for ...",
50 * IntegerValue (12),
51 * MakeIntegerChecker ());
52 * \endcode
53 *
54 * GlobalValues can be set directly by calling GlobalValue::SetValue()
55 * but they can also be set through the \c NS_GLOBAL_VALUE environment variable.
56 * For example, \c NS_GLOBAL_VALUE='Name=Value;OtherName=OtherValue;' would set
57 * global values \c Name and \c OtherName to \c Value and \c OtherValue,
58 * respectively.
59 *
60 * Users of the CommandLine class also get the ability to set global
61 * values through command line arguments to their program:
62 * \c --Name=Value will set global value \c Name to \c Value.
63 */
65{
66 /** Container type for holding all the GlobalValues. */
67 typedef std::vector<GlobalValue*> Vector;
68
69 public:
70 /** Iterator type for the list of all global values. */
71 typedef Vector::const_iterator Iterator;
72
73 /**
74 * Constructor.
75 * \param [in] name the name of this global value.
76 * \param [in] help some help text which describes the purpose of this
77 * global value.
78 * \param [in] initialValue the value to assign to this global value
79 * during construction.
80 * \param [in] checker a pointer to an AttributeChecker which can verify
81 * that any user-supplied value to override the initial
82 * value matches the requested type constraints.
83 */
84 GlobalValue(std::string name,
85 std::string help,
86 const AttributeValue& initialValue,
88
89 /**
90 * Get the name.
91 * \returns The name of this GlobalValue.
92 */
93 std::string GetName() const;
94 /**
95 * Get the help string.
96 * \returns The help text of this GlobalValue.
97 */
98 std::string GetHelp() const;
99 /**
100 * Get the value.
101 * \param [out] value The AttributeValue to set to the value
102 * of this GlobalValue
103 */
104 void GetValue(AttributeValue& value) const;
105 /**
106 * Get the AttributeChecker.
107 * \returns The checker associated to this GlobalValue.
108 */
110 /**
111 * Set the value of this GlobalValue.
112 * \param [in] value the new value to set in this GlobalValue.
113 * \returns \c true if the Global Value was set successfully.
114 */
115 bool SetValue(const AttributeValue& value);
116
117 /** Reset to the initial value. */
118 void ResetInitialValue();
119
120 /**
121 * Iterate over the set of GlobalValues until a matching name is found
122 * and then set its value with GlobalValue::SetValue.
123 *
124 * \param [in] name the name of the global value
125 * \param [in] value the value to set in the requested global value.
126 *
127 * This method cannot fail. It will crash if the input is not valid.
128 */
129 static void Bind(std::string name, const AttributeValue& value);
130
131 /**
132 * Iterate over the set of GlobalValues until a matching name is found
133 * and then set its value with GlobalValue::SetValue.
134 *
135 * \param [in] name the name of the global value
136 * \param [in] value the value to set in the requested global value.
137 * \returns \c true if the value could be set successfully,
138 * \c false otherwise.
139 */
140 static bool BindFailSafe(std::string name, const AttributeValue& value);
141
142 /**
143 * The Begin iterator.
144 * \returns An iterator which represents a pointer to the first GlobalValue registered.
145 */
146 static Iterator Begin();
147 /**
148 * The End iterator.
149 * \returns An iterator which represents a pointer to the last GlobalValue registered.
150 */
151 static Iterator End();
152
153 /**
154 * Finds the GlobalValue with the given name and returns its value
155 *
156 * \param [in] name the name of the GlobalValue to be found
157 * \param [out] value where to store the value of the found GlobalValue
158 *
159 * \return \c true if the GlobalValue was found, \c false otherwise
160 */
161 static bool GetValueByNameFailSafe(std::string name, AttributeValue& value);
162
163 /**
164 * Finds the GlobalValue with the given name and returns its
165 * value.
166 *
167 * This method cannot fail, i.e., it will trigger a
168 * NS_FATAL_ERROR if the requested GlobalValue is not found.
169 *
170 * \param [in] name the name of the GlobalValue to be found
171 * \param [out] value where to store the value of the found GlobalValue
172 */
173 static void GetValueByName(std::string name, AttributeValue& value);
174
175 private:
176 /** Test case needs direct access to GetVector() */
178
179 /**
180 * Get the static vector of all GlobalValues.
181 *
182 * \returns The vector.
183 */
184 static Vector* GetVector();
185 /** Initialize from the \c NS_GLOBAL_VALUE environment variable. */
186 void InitializeFromEnv();
187
188 /** The name of this GlobalValue. */
189 std::string m_name;
190 /** The help string. */
191 std::string m_help;
192 /** The initial value. */
194 /** The current value. */
196 /** The AttributeChecker for this GlobalValue. */
198};
199
200} // namespace ns3
201
202#endif /* GLOBAL_VALUE_H */
ns3::AttributeValue, ns3::AttributeAccessor and ns3::AttributeChecker declarations.
Hold a value for an Attribute.
Definition attribute.h:59
Hold a so-called 'global value'.
Vector::const_iterator Iterator
Iterator type for the list of all global values.
std::string GetHelp() const
Get the help string.
std::vector< GlobalValue * > Vector
Container type for holding all the GlobalValues.
void GetValue(AttributeValue &value) const
Get the value.
static void Bind(std::string name, const AttributeValue &value)
Iterate over the set of GlobalValues until a matching name is found and then set its value with Globa...
static bool GetValueByNameFailSafe(std::string name, AttributeValue &value)
Finds the GlobalValue with the given name and returns its value.
static Iterator Begin()
The Begin iterator.
std::string GetName() const
Get the name.
std::string m_help
The help string.
Ptr< const AttributeChecker > m_checker
The AttributeChecker for this GlobalValue.
Ptr< AttributeValue > m_currentValue
The current value.
bool SetValue(const AttributeValue &value)
Set the value of this GlobalValue.
static void GetValueByName(std::string name, AttributeValue &value)
Finds the GlobalValue with the given name and returns its value.
void ResetInitialValue()
Reset to the initial value.
static bool BindFailSafe(std::string name, const AttributeValue &value)
Iterate over the set of GlobalValues until a matching name is found and then set its value with Globa...
Ptr< const AttributeChecker > GetChecker() const
Get the AttributeChecker.
Ptr< AttributeValue > m_initialValue
The initial value.
static Iterator End()
The End iterator.
GlobalValue(std::string name, std::string help, const AttributeValue &initialValue, Ptr< const AttributeChecker > checker)
Constructor.
std::string m_name
The name of this GlobalValue.
void InitializeFromEnv()
Initialize from the NS_GLOBAL_VALUE environment variable.
static Vector * GetVector()
Get the static vector of all GlobalValues.
Smart pointer class similar to boost::intrusive_ptr.
Test for the ability to get at a GlobalValue.
Every class exported by the ns3 library is enclosed in the ns3 namespace.
ns3::Ptr smart pointer declaration and implementation.