A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
config.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 CONFIG_H
9#define CONFIG_H
10
11#include "ptr.h"
12
13#include <string>
14#include <vector>
15
16/**
17 * @file
18 * @ingroup config
19 * Declaration of the various ns3::Config functions and classes.
20 */
21
22namespace ns3
23{
24
25class AttributeValue;
26class Object;
27class CallbackBase;
28
29/**
30 * @ingroup core
31 * @defgroup config Configuration
32 * @brief Configuration of simulation parameters and tracing.
33 */
34
35/**
36 * @ingroup config
37 * Namespace for the various functions implementing the Config system.
38 */
39namespace Config
40{
41
42/**
43 * @ingroup config
44 * Reset the initial value of every attribute as well as the value of every
45 * global to what they were before any call to SetDefault and SetGlobal.
46 */
47void Reset();
48
49/**
50 * @ingroup config
51 * @param [in] path A path to match attributes.
52 * @param [in] value The value to set in all matching attributes.
53 *
54 * This function will attempt to find attributes which
55 * match the input path and will then set their value to the input
56 * value. If no such attributes are found, the function will throw
57 * a fatal error; use SetFailSafe if the lack of a match is to be permitted.
58 */
59void Set(std::string path, const AttributeValue& value);
60/**
61 * @ingroup config
62 * @param [in] path A path to match attributes.
63 * @param [in] value The value to set in all matching attributes.
64 *
65 * This function will attempt to find attributes which
66 * match the input path and will then set their value to the input
67 * value, and will return true if at least one such attribute is found.
68 * @return \c true if any matching attributes could be set.
69 */
70bool SetFailSafe(std::string path, const AttributeValue& value);
71/**
72 * @ingroup config
73 * @param [in] name The full name of the attribute
74 * @param [in] value The value to set.
75 *
76 * This method overrides the initial value of the
77 * matching attribute. This method cannot fail: it will
78 * crash if the input attribute name or value is invalid.
79 */
80void SetDefault(std::string name, const AttributeValue& value);
81/**
82 * @ingroup config
83 * @param [in] name The full name of the attribute
84 * @param [in] value The value to set.
85 * @returns \c true if the value was set successfully, false otherwise.
86 *
87 * This method overrides the initial value of the
88 * matching attribute.
89 */
90bool SetDefaultFailSafe(std::string name, const AttributeValue& value);
91/**
92 * @ingroup config
93 * @param [in] name The name of the requested GlobalValue.
94 * @param [in] value The value to set
95 *
96 * This method is equivalent to GlobalValue::Bind
97 */
98void SetGlobal(std::string name, const AttributeValue& value);
99/**
100 * @ingroup config
101 * @param [in] name The name of the requested GlobalValue.
102 * @param [in] value The value to set
103 * @return \c true if the GlobalValue could be set.
104 *
105 * This method is equivalent to GlobalValue::BindFailSafe
106 */
107bool SetGlobalFailSafe(std::string name, const AttributeValue& value);
108/**
109 * @ingroup config
110 * @param [in] path A path to match trace sources.
111 * @param [in] cb The callback to connect to the matching trace sources.
112 *
113 * This function will attempt to find all trace sources which
114 * match the input path and will then connect the input callback
115 * to them. If no matching trace sources are found, this method will
116 * throw a fatal error. Use ConnectWithoutContextFailSafe if the absence
117 * of matching trace sources should not be fatal.
118 */
119void ConnectWithoutContext(std::string path, const CallbackBase& cb);
120/**
121 * @ingroup config
122 * @param [in] path A path to match trace sources.
123 * @param [in] cb The callback to connect to the matching trace sources.
124 *
125 * This function will attempt to find all trace sources which
126 * match the input path and will then connect the input callback
127 * to them. If no matching trace sources are found, this method will
128 * return false; otherwise true.
129 * @returns \c true if any trace sources could be connected.
130 */
131bool ConnectWithoutContextFailSafe(std::string path, const CallbackBase& cb);
132/**
133 * @ingroup config
134 * @param [in] path A path to match trace sources.
135 * @param [in] cb The callback to disconnect to the matching trace sources.
136 *
137 * This function undoes the work of Config::Connect.
138 */
139void DisconnectWithoutContext(std::string path, const CallbackBase& cb);
140/**
141 * @ingroup config
142 * @param [in] path A path to match trace sources.
143 * @param [in] cb The callback to connect to the matching trace sources.
144 *
145 * This function will attempt to find all trace sources which
146 * match the input path and will then connect the input callback
147 * to them in such a way that the callback will receive an extra
148 * context string upon trace event notification.
149 * If no matching trace sources are found, this method will
150 * throw a fatal error. Use ConnectFailSafe if the absence
151 * of matching trace sources should not be fatal.
152 */
153void Connect(std::string path, const CallbackBase& cb);
154/**
155 * @ingroup config
156 * @param [in] path A path to match trace sources.
157 * @param [in] cb The callback to connect to the matching trace sources.
158 *
159 * This function will attempt to find all trace sources which
160 * match the input path and will then connect the input callback
161 * to them in such a way that the callback will receive an extra
162 * context string upon trace event notification.
163 * @returns \c true if any trace sources could be connected.
164 */
165bool ConnectFailSafe(std::string path, const CallbackBase& cb);
166/**
167 * @ingroup config
168 * @param [in] path A path to match trace sources.
169 * @param [in] cb The callback to connect to the matching trace sources.
170 *
171 * This function undoes the work of Config::ConnectWithContext.
172 */
173void Disconnect(std::string path, const CallbackBase& cb);
174
175/**
176 * @ingroup config
177 * @brief hold a set of objects which match a specific search string.
178 *
179 * This class also allows you to perform a set of configuration operations
180 * on the set of matching objects stored in the container. Specifically,
181 * it is possible to perform bulk Connects and Sets.
182 */
184{
185 public:
186 /** Const iterator over the objects in this container. */
187 typedef std::vector<Ptr<Object>>::const_iterator Iterator;
189 /**
190 * Constructor used only by implementation.
191 *
192 * @param [in] objects The vector of objects to store in this container.
193 * @param [in] contexts The corresponding contexts.
194 * @param [in] path The path used for object matching.
195 */
196 MatchContainer(const std::vector<Ptr<Object>>& objects,
197 const std::vector<std::string>& contexts,
198 std::string path);
199
200 /**
201 * @returns An iterator which points to the first item in the container
202 * @{
203 */
205
207 {
208 return Begin();
209 }
210
211 /** @} */
212 /**
213 * @returns An iterator which points to the last item in the container
214 * @{
215 */
217
219 {
220 return End();
221 }
222
223 /** @} */
224 /**
225 * @returns The number of items in the container
226 * @{
227 */
228 std::size_t GetN() const;
229
230 std::size_t size() const
231 {
232 return GetN();
233 }
234
235 /** @} */
236 /**
237 * @param [in] i Index of item to lookup ([0,n[)
238 * @returns The item requested.
239 */
240 Ptr<Object> Get(std::size_t i) const;
241 /**
242 * @param [in] i Index of item to lookup ([0,n[)
243 * @returns The fully-qualified matching path associated
244 * to the requested item.
245 *
246 * The matching patch uniquely identifies the requested object.
247 */
248 std::string GetMatchedPath(uint32_t i) const;
249 /**
250 * @returns The path used to perform the object matching.
251 */
252 std::string GetPath() const;
253
254 /**
255 * @param [in] name Name of attribute to set
256 * @param [in] value Value to set to the attribute
257 *
258 * Set the specified attribute value to all the objects stored in this
259 * container. This method will raise a fatal error if no such attribute
260 * exists; use SetFailSafe if the absence of the attribute is to be
261 * permitted.
262 * \sa ns3::Config::Set
263 */
264 void Set(std::string name, const AttributeValue& value);
265 /**
266 * @param [in] name Name of attribute to set
267 * @param [in] value Value to set to the attribute
268 *
269 * Set the specified attribute value to all the objects stored in this
270 * container. This method will return true if any attributes could be
271 * set, and false otherwise.
272 * @returns \c true if any attributes could be set.
273 */
274 bool SetFailSafe(std::string name, const AttributeValue& value);
275 /**
276 * @param [in] name The name of the trace source to connect to
277 * @param [in] cb The sink to connect to the trace source
278 *
279 * Connect the specified sink to all the objects stored in this
280 * container. This method will raise a fatal error if no objects could
281 * be connected; use ConnectFailSafe if no connections is a valid possible
282 * outcome.
283 * \sa ns3::Config::Connect
284 */
285 void Connect(std::string name, const CallbackBase& cb);
286 /**
287 * @param [in] name The name of the trace source to connect to
288 * @param [in] cb The sink to connect to the trace source
289 *
290 * Connect the specified sink to all the objects stored in this
291 * container. This method will return true if any trace sources could be
292 * connected, and false otherwise.
293 * @returns \c true if any trace sources could be connected.
294 */
295 bool ConnectFailSafe(std::string name, const CallbackBase& cb);
296 /**
297 * @param [in] name The name of the trace source to connect to
298 * @param [in] cb The sink to connect to the trace source
299 *
300 * Connect the specified sink to all the objects stored in this
301 * container. This method will raise a fatal error if no objects could
302 * be connected; use ConnectWithoutContextFailSafe if no connections is
303 * a valid possible outcome.
304 * \sa ns3::Config::ConnectWithoutContext
305 */
306 void ConnectWithoutContext(std::string name, const CallbackBase& cb);
307 /**
308 * @param [in] name The name of the trace source to connect to
309 * @param [in] cb The sink to connect to the trace source
310 *
311 * Connect the specified sink to all the objects stored in this
312 * container. This method will return true if any trace sources could be
313 * connected, and false otherwise.
314 * @returns \c true if any trace sources could be connected.
315 */
316 bool ConnectWithoutContextFailSafe(std::string name, const CallbackBase& cb);
317 /**
318 * @param [in] name The name of the trace source to disconnect from
319 * @param [in] cb The sink to disconnect from the trace source
320 *
321 * Disconnect the specified sink from all the objects stored in this
322 * container.
323 * \sa ns3::Config::Disconnect
324 */
325 void Disconnect(std::string name, const CallbackBase& cb);
326 /**
327 * @param [in] name The name of the trace source to disconnect from
328 * @param [in] cb The sink to disconnect from the trace source
329 *
330 * Disconnect the specified sink from all the objects stored in this
331 * container.
332 * \sa ns3::Config::DisconnectWithoutContext
333 */
334 void DisconnectWithoutContext(std::string name, const CallbackBase& cb);
335
336 private:
337 /** The list of objects in this container. */
338 std::vector<Ptr<Object>> m_objects;
339 /** The context for each object. */
340 std::vector<std::string> m_contexts;
341 /** The path used to perform the object matching. */
342 std::string m_path;
343};
344
345/**
346 * @ingroup config
347 * @param [in] path The path to perform a match against
348 * @returns A container which contains all the objects which match the input
349 * path.
350 */
351MatchContainer LookupMatches(std::string path);
352
353/**
354 * @ingroup config
355 * @param [in] obj A new root object
356 *
357 * Each root object is used during path matching as
358 * the root of the path by Config::Connect, and Config::Set.
359 */
361/**
362 * @ingroup config
363 * @param [in] obj A new root object
364 *
365 * This function undoes the work of Config::RegisterRootNamespaceObject.
366 */
368
369/**
370 * @ingroup config
371 * @returns The number of registered root namespace objects.
372 */
373std::size_t GetRootNamespaceObjectN();
374
375/**
376 * @ingroup config
377 * @param [in] i The index of the requested object.
378 * @returns The requested root namespace object
379 */
381
382} // namespace Config
383
384} // namespace ns3
385
386#endif /* CONFIG_H */
Hold a value for an Attribute.
Definition attribute.h:59
Base class for Callback class.
Definition callback.h:344
hold a set of objects which match a specific search string.
Definition config.h:184
bool SetFailSafe(std::string name, const AttributeValue &value)
Definition config.cc:108
void Connect(std::string name, const CallbackBase &cb)
Definition config.cc:121
void DisconnectWithoutContext(std::string name, const CallbackBase &cb)
Definition config.cc:180
void Set(std::string name, const AttributeValue &value)
Definition config.cc:96
Ptr< Object > Get(std::size_t i) const
Definition config.cc:75
void Disconnect(std::string name, const CallbackBase &cb)
Definition config.cc:167
std::string GetMatchedPath(uint32_t i) const
Definition config.cc:82
MatchContainer::Iterator End() const
Definition config.cc:61
MatchContainer::Iterator begin() const
Definition config.h:206
bool ConnectFailSafe(std::string name, const CallbackBase &cb)
Definition config.cc:130
std::string GetPath() const
Definition config.cc:89
bool ConnectWithoutContextFailSafe(std::string name, const CallbackBase &cb)
Definition config.cc:154
std::size_t size() const
Definition config.h:230
std::string m_path
The path used to perform the object matching.
Definition config.h:342
void ConnectWithoutContext(std::string name, const CallbackBase &cb)
Definition config.cc:145
std::size_t GetN() const
Definition config.cc:68
std::vector< Ptr< Object > >::const_iterator Iterator
Const iterator over the objects in this container.
Definition config.h:187
MatchContainer::Iterator end() const
Definition config.h:218
std::vector< Ptr< Object > > m_objects
The list of objects in this container.
Definition config.h:338
MatchContainer::Iterator Begin() const
Definition config.cc:54
std::vector< std::string > m_contexts
The context for each object.
Definition config.h:340
Smart pointer class similar to boost::intrusive_ptr.
void Reset()
Reset the initial value of every attribute as well as the value of every global to what they were bef...
Definition config.cc:848
void SetGlobal(std::string name, const AttributeValue &value)
Definition config.cc:929
bool SetFailSafe(std::string path, const AttributeValue &value)
Definition config.cc:876
void SetDefault(std::string name, const AttributeValue &value)
Definition config.cc:883
void Disconnect(std::string path, const CallbackBase &cb)
Definition config.cc:984
void Connect(std::string path, const CallbackBase &cb)
Definition config.cc:967
MatchContainer LookupMatches(std::string path)
Definition config.cc:991
void DisconnectWithoutContext(std::string path, const CallbackBase &cb)
Definition config.cc:960
void ConnectWithoutContext(std::string path, const CallbackBase &cb)
Definition config.cc:943
bool ConnectFailSafe(std::string path, const CallbackBase &cb)
Definition config.cc:977
void UnregisterRootNamespaceObject(Ptr< Object > obj)
Definition config.cc:1005
Ptr< Object > GetRootNamespaceObject(uint32_t i)
Definition config.cc:1019
bool SetGlobalFailSafe(std::string name, const AttributeValue &value)
Definition config.cc:936
void Set(std::string path, const AttributeValue &value)
Definition config.cc:869
void RegisterRootNamespaceObject(Ptr< Object > obj)
Definition config.cc:998
std::size_t GetRootNamespaceObjectN()
Definition config.cc:1012
bool SetDefaultFailSafe(std::string fullName, const AttributeValue &value)
Definition config.cc:893
bool ConnectWithoutContextFailSafe(std::string path, const CallbackBase &cb)
Definition config.cc:953
Every class exported by the ns3 library is enclosed in the ns3 namespace.
ns3::Ptr smart pointer declaration and implementation.