A Discrete-Event Network Simulator
Home
Tutorials ▼
English
Documentation ▼
Installation
Manual
Models
Contributing
Wiki
Development ▼
API Docs
Issue Tracker
Merge Requests
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
19
namespace
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
*/
27
class
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
440
template
<
typename
T>
441
/* static */
442
Ptr<T>
443
Names::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
456
template
<
typename
T>
457
/* static */
458
Ptr<T>
459
Names::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
472
template
<
typename
T>
473
/* static */
474
Ptr<T>
475
Names::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 */
ns3::Names
A directory of name and Ptr<Object> associations that allows us to give any ns3 Object a name.
Definition
names.h:28
ns3::Names::Rename
static void Rename(std::string oldpath, std::string newname)
Rename a previously associated name.
Definition
names.cc:772
ns3::Names::FindInternal
static Ptr< Object > FindInternal(std::string path)
Non-templated internal version of Names::Find.
Definition
names.cc:839
ns3::Names::Add
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
ns3::Names::Find
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
ns3::Names::Clear
static void Clear()
Clear the list of objects associated with names.
Definition
names.cc:832
ns3::Names::FindName
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
ns3::Names::FindPath
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
ns3::Ptr
Smart pointer class similar to boost::intrusive_ptr.
Definition
mpi-test-fixtures.h:37
ns3
Every class exported by the ns3 library is enclosed in the ns3 namespace.
object.h
ns3::Object class declaration, which is the root of the Object hierarchy and Aggregation.
ptr.h
ns3::Ptr smart pointer declaration and implementation.
src
core
model
names.h
Generated on Wed Oct 9 2024 01:03:22 for ns-3 by
1.11.0