A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
names.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2009 University of Washington
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 */
6
7#ifndef OBJECT_NAMES_H
8#define OBJECT_NAMES_H
9
10#include "object.h"
11#include "ptr.h"
12
13/**
14 * \file
15 * \ingroup config
16 * Declaration of class ns3::Names.
17 */
18
19namespace ns3
20{
21
22/**
23 * \ingroup config
24 * \brief A directory of name and Ptr<Object> associations that allows
25 * us to give any ns3 Object a name.
26 */
27class Names
28{
29 public:
30 /**
31 * \brief Add the association between the string "name" and the
32 * Ptr<Object> obj.
33 *
34 * The name may begin either with "/Names" to explicitly call out
35 * the fact that the name provided is installed under the root of
36 * the name space, or it may begin with the name of the first object
37 * in the path. For example, Names::Add ("/Names/client", obj) and
38 * Names::Add ("client", obj) accomplish exactly the same thing. A
39 * name at a given level in the name space path must be unique. In
40 * the case of the example above, it would be illegal to try and
41 * associate a different object with the same name: "client" at the
42 * same level ("/Names") in the path.
43 *
44 * As well as specifying a name at the root of the "/Names"
45 * namespace, the name parameter can contain a path that fully
46 * qualifies the name to be added. For example, if you previously
47 * have named an object "client" in the root namespace as above, you
48 * could name an object "under" that name by making a call like
49 * Names::Add ("/Names/client/eth0", obj). This will define the
50 * name "eth0" and make it reachable using the path specified. Note
51 * that Names::Add ("client/eth0", obj) would accomplish exactly the
52 * same thing.
53 *
54 * Duplicate names are not allowed at the same level in a path,
55 * however you may associate similar names with different paths.
56 * For example, if you define "/Names/Client", you may not define
57 * another "/Names/Client" just as you may not have two files with
58 * the same name in a classical filesystem. However, you may have
59 * "/Names/Client/eth0" and "/Names/Server/eth0" defined at the same
60 * time just as you might have different files of the same name
61 * under different directories.
62 *
63 * \param [in] name The name of the object you want to associate; which may be
64 * prepended with a path to that object.
65 * \param [in] object A smart pointer to the object itself.
66 */
67 static void Add(std::string name, Ptr<Object> object);
68
69 /**
70 * \brief An intermediate form of Names::Add allowing you to provide
71 * a path to the parent object (under which you want this name to be
72 * defined) in the form of a name path string.
73 *
74 * In some cases, it is desirable to break up the path used to
75 * describe an item in the names namespace into a path and a name.
76 * This is analogous to a file system operation in which you provide
77 * a directory name and a file name.
78 *
79 * For example, consider a situation where you have previously named
80 * an object "/Names/server". If you further want to create an
81 * association for between a Ptr<Object> object that you want to
82 * live "under" the server in the name space -- perhaps "eth0" --
83 * you could do this in two ways, depending on which was more
84 * convenient: Names::Add ("/Names/server/eth0", object) or, using
85 * the split path and name approach, Names::Add ("/Names/server",
86 * "eth0", object).
87 *
88 * Duplicate names are not allowed at the same level in a path,
89 * however you may associate similar names with different paths.
90 * For example, if you define "/Names/Client", you may not define
91 * another "/Names/Client" just as you may not have two files with
92 * the same name in a classical filesystem. However, you may have
93 * "/Names/Client/eth0" and "/Names/Server/eth0" defined at the same
94 * time just as you might have different files of the same name
95 * under different directories.
96 *
97 * \param [in] path A path name describing a previously named object
98 * under which you want this new name to be defined.
99 * \param [in] name The name of the object you want to associate.
100 * \param [in] object A smart pointer to the object itself.
101 *
102 * \see Names::Add (Ptr<Object>,std::string,Ptr<Object>);
103 */
104 static void Add(std::string path, std::string name, Ptr<Object> object);
105
106 /**
107 * \brief A low-level form of Names::Add allowing you to specify the
108 * path to the parent object (under which you want this name to be
109 * defined) in the form of a previously named object.
110 *
111 * In some use cases, it is desirable to break up the path in the
112 * names name space into a path and a name. This is analogous to a
113 * file system operation in which you provide a directory name and a
114 * file name. Recall that the path string actually refers to a
115 * previously named object, "under" which you want to accomplish
116 * some naming action.
117 *
118 * However, the path is sometimes not available, and you only have
119 * the object that is represented by the path in the names name
120 * space. To support this use-case in a reasonably high-performance
121 * way, the path string is can be replaced by the object pointer to
122 * which that path would refer. In the spirit of the Config code
123 * where this use-case is most prominent, we refer to this object as
124 * the "context" for the names operation.
125 *
126 * You can think of the context roughly as the inode number of a
127 * directory file in Unix. The inode number can be used to look up
128 * the directory file which contains the list of file names defined
129 * at that directory level. Similarly the context is used to look
130 * up an internal name service entry which contains the names
131 * defined for that context.
132 *
133 * For example, consider a situation where you have previously named
134 * an object "/Names/server". If you further want to create an
135 * association for between a Ptr<Object> object that you want to
136 * live "under" the server in the name space -- perhaps "eth0" --
137 * you could do this by providing a complete path to the new name:
138 * Names::Add ("/Names/server/eth0", object). If, however,
139 * somewhere in your code you only had a pointer to the server, say
140 * Ptr<Node> node, and not a handy path string, you could also
141 * accomplish this by Names::Add (node, "eth0", object).
142 *
143 * Duplicate names are not allowed at the same level in a path. In
144 * the case of this method, the context object gives the same
145 * information as a path string. You may associate similar names
146 * with different paths. For example, if you define"/Names/Client",
147 * you may not define another "/Names/Client" just as you may not
148 * have two files with the same name in a classical filesystem.
149 * However, you may have "/Names/Client/eth0" and
150 * "/Names/Server/eth0" defined at the same time just as you might
151 * have different files of the same name under different
152 * directories.
153 *
154 * \param [in] context A smart pointer to an object that is used
155 * in place of the path under which you want this new
156 * name to be defined.
157 * \param [in] name The name of the object you want to associate.
158 * \param [in] object A smart pointer to the object itself.
159 */
160 static void Add(Ptr<Object> context, std::string name, Ptr<Object> object);
161
162 /**
163 * \brief Rename a previously associated name.
164 *
165 * The name may begin either with "/Names" to explicitly call out
166 * the fact that the name provided is installed under the root of
167 * the name space, or it may begin with the name of the first object
168 * in the path. For example, Names::Rename ("/Names/client",
169 * "server") and Names::Rename ("client", "server") accomplish
170 * exactly the same thing. Names at a given level in the name space
171 * path must be unique. In the case of the example above, it would
172 * be illegal to try and rename a different object to the same name:
173 * "server" at the same level ("/Names") in the path.
174 *
175 * As well as specifying a name at the root of the "/Names"
176 * namespace, the name parameter can contain a path that fully
177 * qualifies the name to be changed. For example, if you previously
178 * have (re)named an object "server" in the root namespace as above,
179 * you could then rename an object "under" that name by making a
180 * call like Names::Rename ("/Names/server/csma", "eth0"). This
181 * will rename the object previously associated with
182 * "/Names/server/csma" to "eth0" and make leave it reachable using
183 * the path "/Names/server/eth0". Note that Names::Rename
184 * ("server/csma", "eth0") would accomplish exactly the same thing.
185 *
186 * \param [in] oldpath The current path name to the object you want
187 * to change.
188 * \param [in] newname The new name of the object you want to change.
189 *
190 * \see Names::Add (std::string name, Ptr<Object> obj)
191 */
192 static void Rename(std::string oldpath, std::string newname);
193
194 /**
195 * \brief An intermediate form of Names::Rename allowing you to
196 * provide a path to the parent object (under which you want this
197 * name to be changed) in the form of a name path string.
198 *
199 * In some cases, it is desirable to break up the path used to
200 * describe an item in the names namespace into a path and a name.
201 * This is analogous to a file system operation in which you provide
202 * a directory name and a file name.
203 *
204 * For example, consider a situation where you have previously named
205 * an object "/Names/server/csma". If you want to change the name
206 * "csma" to "eth0", you could do this in two ways, depending on
207 * which was more convenient: Names::Rename ("/Names/server/csma",
208 * "eth0") or, using the split path and name approach, Names::Rename
209 * ("/Names/server", "csma", "eth0").
210 *
211 * \param [in] path A path name describing a previously named object
212 * under which you want this name change to occur
213 * (cf. directory).
214 * \param [in] oldname The currently defined name of the object.
215 * \param [in] newname The new name you want the object to have.
216 */
217 static void Rename(std::string path, std::string oldname, std::string newname);
218
219 /**
220 * \brief A low-level form of Names::Rename allowing you to specify
221 * the path to the parent object (under which you want this name to
222 * be changed) in the form of a previously named object.
223 *
224 * In some use cases, it is desirable to break up the path in the
225 * names name space into a path and a name. This is analogous to a
226 * file system operation in which you provide a directory name and a
227 * file name. Recall that the path string actually refers to a
228 * previously named object, "under" which you want to accomplish
229 * some naming action.
230 *
231 * However, the path is sometimes not available, and you only have
232 * the object that is represented by the path in the names name
233 * space. To support this use-case in a reasonably high-performance
234 * way, the path string is can be replaced by the object pointer to
235 * which that path would refer. In the spirit of the Config code
236 * where this use-case is most prominent, we refer to this object as
237 * the "context" for the names operation.
238 *
239 * You can think of the context roughly as the inode number of a
240 * directory file in Unix. The inode number can be used to look up
241 * the directory file which contains the list of file names defined
242 * at that directory level. Similarly the context is used to look
243 * up an internal name service entry which contains the names
244 * defined for that context.
245 *
246 * For example, consider a situation where you have previously named
247 * an object "/Names/server/csma". If you later decide to rename
248 * the csma object to say "eth0" -- you could do this by providing a
249 * complete path as in Names::Rename ("/Names/server/csma", "eth0").
250 * If, however, somewhere in your code you only had a pointer to the
251 * server, and not a handy path string, say Ptr<Node> node, you
252 * could also accomplish this by Names::Rename (node, "csma",
253 * "eth0").
254 *
255 * \param [in] context A smart pointer to an object that is used
256 * in place of the path under which you want this
257 * new name to be defined.
258 * \param [in] oldname The current shortname of the object you want
259 * to change.
260 * \param [in] newname The new shortname of the object you want
261 * to change.
262 */
263 static void Rename(Ptr<Object> context, std::string oldname, std::string newname);
264
265 /**
266 * \brief Given a pointer to an object, look to see if that object
267 * has a name associated with it and, if so, return the name of the
268 * object otherwise return an empty string.
269 *
270 * An object can be referred to in two ways. Either you can talk
271 * about it using its fully qualified path name, for example,
272 * "/Names/client/eth0" or you can refer to it by its name, in this
273 * case "eth0".
274 *
275 * This method returns the name of the object, e.g., "eth0".
276 *
277 * \param [in] object A smart pointer to an object for which you want
278 * to find its name.
279 *
280 * \returns A string containing the name of the object if found,
281 * otherwise the empty string.
282 */
283 static std::string FindName(Ptr<Object> object);
284
285 /**
286 * \brief Given a pointer to an object, look to see if that object
287 * has a name associated with it and return the fully qualified name
288 * path of the object otherwise return an empty string.
289 *
290 * An object can be referred to in two ways. Either you can talk
291 * about it using its fully qualified path name, for example,
292 * "/Names/client/eth0" or you can refer to it by its name, in this
293 * case "eth0".
294 *
295 * This method returns the name path of the object, e.g.,
296 * "Names/client/eth0".
297 *
298 * \param [in] object A smart pointer to an object for which you
299 * want to find its fullname.
300 *
301 * \returns A string containing the name path of the object,
302 * otherwise the empty string.
303 */
304 static std::string FindPath(Ptr<Object> object);
305
306 /**
307 * \brief Clear the list of objects associated with names.
308 */
309
310 static void Clear();
311
312 /**
313 * \brief Given a name path string, look to see if there's an object
314 * in the system with that associated to it. If there is, do a
315 * GetObject on the resulting object to convert it to the requested
316 * typename and return it.
317 *
318 * An object can be referred to in two ways. Either you can talk
319 * about it using its fully qualified path name, for example,
320 * "/Names/client/eth0" or you can refer to it by its name, in this
321 * case "eth0".
322 *
323 * This method requires that the name path of the object be
324 * provided, e.g., "Names/client/eth0".
325 *
326 * \param [in] path A string containing a name space path used
327 * to locate the object.
328 *
329 * \returns A smart pointer to the named object converted to
330 * the requested type.
331 */
332 template <typename T>
333 static Ptr<T> Find(std::string path);
334
335 /**
336 * \brief Given a path to an object and an object name, look through
337 * the names defined under the path to see if there's an object
338 * there with the given name.
339 *
340 * In some cases, it is desirable to break up the path used to
341 * describe an item in the names namespace into a path and a name.
342 * This is analogous to a file system operation in which you provide
343 * a directory name and a file name.
344 *
345 * For example, consider a situation where you have previously named
346 * an object "/Names/server/eth0". If you want to discover the
347 * object which you associated with this path, you could do this in
348 * two ways, depending on which was more convenient: Names::Find
349 * ("/Names/server/eth0") or, using the split path and name
350 * approach, Names::Find ("/Names/server", "eth0").
351 *
352 * \param [in] path A path name describing a previously named object
353 * under which you want to look for the specified name.
354 * \param [in] name A string containing a name to search for.
355 *
356 * \returns A smart pointer to the named object converted to
357 * the requested type.
358 */
359 template <typename T>
360 static Ptr<T> Find(std::string path, std::string name);
361
362 /**
363 * \brief Given a path to an object and an object name, look through
364 * the names defined under the path to see if there's an object
365 * there with the given name.
366 *
367 * In some cases, it is desirable to break up the path used to
368 * describe an item in the names namespace into a path and a name.
369 * This is analogous to a file system operation in which you provide
370 * a directory name and a file name.
371 *
372 * For example, consider a situation where you have previously named
373 * an object "/Names/server/eth0". If you want to discover the
374 * object which you associated with this path, you could do this in
375 * two ways, depending on which was more convenient: Names::Find
376 * ("/Names/server/eth0") or, using the split path and name
377 * approach, Names::Find ("/Names/server", "eth0").
378 *
379 * However, the path is sometimes not available, and you only have
380 * the object that is represented by the path in the names name
381 * space. To support this use-case in a reasonably high-performance
382 * way, the path string is can be replaced by the object pointer to
383 * which that path would refer. In the spirit of the Config code
384 * where this use-case is most prominent, we refer to this object as
385 * the "context" for the names operation.
386 *
387 * You can think of the context roughly as the inode number of a
388 * directory file in Unix. The inode number can be used to look up
389 * the directory file which contains the list of file names defined
390 * at that directory level. Similarly the context is used to look
391 * up an internal name service entry which contains the names
392 * defined for that context.
393 *
394 * \param [in] context A smart pointer to an object that is used
395 * in place of the path under which you want this
396 * new name to be defined.
397 * \param [in] name A string containing a name to search for.
398 *
399 * \returns A smart pointer to the named object converted to
400 * the requested type.
401 */
402 template <typename T>
403 static Ptr<T> Find(Ptr<Object> context, std::string name);
404
405 private:
406 /**
407 * \brief Non-templated internal version of Names::Find
408 *
409 * \param [in] path A string containing the path of the object
410 * to look for.
411 *
412 * \returns A smart pointer to the named object.
413 */
414 static Ptr<Object> FindInternal(std::string path);
415
416 /**
417 * \brief Non-templated internal version of Names::Find
418 *
419 * \param [in] path A string containing the path to search
420 * for the object in.
421 * \param [in] name A string containing the name of the object
422 * to look for.
423 *
424 * \returns A smart pointer to the named object.
425 */
426 static Ptr<Object> FindInternal(std::string path, std::string name);
427
428 /**
429 * \brief Non-templated internal version of Names::Find
430 *
431 * \param [in] context A smart pointer to an object under which
432 * you want to look for the provided name.
433 * \param [in] name A string containing the name to look for.
434 *
435 * \returns A smart pointer to the named object.
436 */
437 static Ptr<Object> FindInternal(Ptr<Object> context, std::string name);
438};
439
440template <typename T>
441/* static */
442Ptr<T>
443Names::Find(std::string path)
444{
445 Ptr<Object> obj = FindInternal(path);
446 if (obj)
447 {
448 return obj->GetObject<T>();
449 }
450 else
451 {
452 return nullptr;
453 }
454}
455
456template <typename T>
457/* static */
458Ptr<T>
459Names::Find(std::string path, std::string name)
460{
461 Ptr<Object> obj = FindInternal(path, name);
462 if (obj)
463 {
464 return obj->GetObject<T>();
465 }
466 else
467 {
468 return nullptr;
469 }
470}
471
472template <typename T>
473/* static */
474Ptr<T>
475Names::Find(Ptr<Object> context, std::string name)
476{
477 Ptr<Object> obj = FindInternal(context, name);
478 if (obj)
479 {
480 return obj->GetObject<T>();
481 }
482 else
483 {
484 return nullptr;
485 }
486}
487
488} // namespace ns3
489
490#endif /* OBJECT_NAMES_H */
A directory of name and Ptr<Object> associations that allows us to give any ns3 Object a name.
Definition names.h:28
static void Rename(std::string oldpath, std::string newname)
Rename a previously associated name.
Definition names.cc:772
static Ptr< Object > FindInternal(std::string path)
Non-templated internal version of Names::Find.
Definition names.cc:839
static void Add(std::string name, Ptr< Object > object)
Add the association between the string "name" and the Ptr<Object> obj.
Definition names.cc:764
static Ptr< T > Find(std::string path)
Given a name path string, look to see if there's an object in the system with that associated to it.
Definition names.h:443
static void Clear()
Clear the list of objects associated with names.
Definition names.cc:832
static std::string FindName(Ptr< Object > object)
Given a pointer to an object, look to see if that object has a name associated with it and,...
Definition names.cc:818
static std::string FindPath(Ptr< Object > object)
Given a pointer to an object, look to see if that object has a name associated with it and return the...
Definition names.cc:825
Smart pointer class similar to boost::intrusive_ptr.
Every class exported by the ns3 library is enclosed in the ns3 namespace.
ns3::Object class declaration, which is the root of the Object hierarchy and Aggregation.
ns3::Ptr smart pointer declaration and implementation.