author | Tom Henderson <tomh@tomh.org> |
Mon, 03 Jan 2011 14:35:44 -0800 | |
changeset 6766 | 4caf532b12c3 |
parent 6751 | 700a92acb8ec |
permissions | -rw-r--r-- |
6742
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
1 |
.. include:: replace.txt |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
2 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
3 |
Attributes |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
4 |
---------- |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
5 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
6 |
In |ns3| simulations, there are two main aspects to configuration: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
7 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
8 |
* the simulation topology and how objects are connected |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
9 |
* the values used by the models instantiated in the topology |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
10 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
11 |
This chapter focuses on the second item above: how the many values in use in |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
12 |
|ns3| are organized, documented, and modifiable by |ns3| users. The |ns3| |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
13 |
attribute system is also the underpinning of how traces and statistics are |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
14 |
gathered in the simulator. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
15 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
16 |
Before delving into details of the attribute value system, it will help to |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
17 |
review some basic properties of class :cpp:class:`ns3::Object`. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
18 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
19 |
Object Overview |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
20 |
*************** |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
21 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
22 |
|ns3| is fundamentally a C++ object-based system. By this we mean that new C++ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
23 |
classes (types) can be declared, defined, and subclassed as usual. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
24 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
25 |
Many |ns3| objects inherit from the :cpp:class:`ns3::Object` base class. These |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
26 |
objects have some additional properties that we exploit for organizing the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
27 |
system and improving the memory management of our objects: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
28 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
29 |
* a "metadata" system that links the class name to a lot of meta-information |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
30 |
about the object, including the base class of the subclass, the set of |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
31 |
accessible constructors in the subclass, and the set of "attributes" of the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
32 |
subclass |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
33 |
* a reference counting smart pointer implementation, for memory management. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
34 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
35 |
|ns3| objects that use the attribute system derive from either |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
36 |
:cpp:class:`ns3::Object` or :cpp:class:`ns3::ObjectBase`. Most |ns3| objects we |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
37 |
will discuss derive from :cpp:class:`ns3::Object`, but a few that are outside |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
38 |
the smart pointer memory management framework derive from |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
39 |
:cpp:class:`ns3::ObjectBase`. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
40 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
41 |
Let's review a couple of properties of these objects. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
42 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
43 |
Smart pointers |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
44 |
************** |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
45 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
46 |
As introduced in the |ns3| tutorial, |ns3| objects are memory managed by a |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
47 |
`reference counting smart pointer implementation |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
48 |
<http://en.wikipedia.org/wiki/Smart_pointer>`_, class :cpp:class:`ns3::Ptr`. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
49 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
50 |
Smart pointers are used extensively in the |ns3| APIs, to avoid passing |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
51 |
references to heap-allocated objects that may cause memory leaks. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
52 |
For most basic usage (syntax), treat a smart pointer like a regular pointer::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
53 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
54 |
Ptr<WifiNetDevice> nd = ...; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
55 |
nd->CallSomeFunction (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
56 |
// etc. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
57 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
58 |
CreateObject |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
59 |
++++++++++++ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
60 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
61 |
As we discussed above in :ref:`Memory management and class Ptr`, at the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
62 |
lowest-level API, objects of type :cpp:class:`ns3::Object` are not instantiated |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
63 |
using ``operator new`` as usual but instead by a templated function called |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
64 |
:cpp:func:`CreateObject()`. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
65 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
66 |
A typical way to create such an object is as follows::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
67 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
68 |
Ptr<WifiNetDevice> nd = CreateObject<WifiNetDevice> (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
69 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
70 |
You can think of this as being functionally equivalent to::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
71 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
72 |
WifiNetDevice* nd = new WifiNetDevice (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
73 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
74 |
Objects that derive from :cpp:class:`ns3::Object` must be allocated on the heap |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
75 |
using CreateObject(). Those deriving from :cpp:class:`ns3::ObjectBase`, such as |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
76 |
|ns3| helper functions and packet headers and trailers, can be allocated on the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
77 |
stack. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
78 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
79 |
In some scripts, you may not see a lot of CreateObject() calls in the code; this |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
80 |
is because there are some helper objects in effect that are doing the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
81 |
CreateObject()s for you. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
82 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
83 |
TypeId |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
84 |
++++++ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
85 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
86 |
|ns3| classes that derive from class ns3::Object can include a metadata class |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
87 |
called ``TypeId`` that records meta-information about the class, for use in the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
88 |
object aggregation and component manager systems: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
89 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
90 |
* a unique string identifying the class |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
91 |
* the base class of the subclass, within the metadata system |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
92 |
* the set of accessible constructors in the subclass |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
93 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
94 |
Object Summary |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
95 |
++++++++++++++ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
96 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
97 |
Putting all of these concepts together, let's look at a specific |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
98 |
example: class :cpp:class:`ns3::Node`. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
99 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
100 |
The public header file node.h has a declaration that includes a static GetTypeId |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
101 |
function call::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
102 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
103 |
class Node : public Object |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
104 |
{ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
105 |
public: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
106 |
static TypeId GetTypeId (void); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
107 |
... |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
108 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
109 |
This is defined in the ``node.cc`` file as follows::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
110 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
111 |
TypeId |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
112 |
Node::GetTypeId (void) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
113 |
{ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
114 |
static TypeId tid = TypeId ("ns3::Node") |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
115 |
.SetParent<Object> () |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
116 |
.AddConstructor<Node> () |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
117 |
.AddAttribute ("DeviceList", "The list of devices associated to this Node.", |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
118 |
ObjectVectorValue (), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
119 |
MakeObjectVectorAccessor (&Node::m_devices), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
120 |
MakeObjectVectorChecker<NetDevice> ()) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
121 |
.AddAttribute ("ApplicationList", "The list of applications associated to this Node.", |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
122 |
ObjectVectorValue (), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
123 |
MakeObjectVectorAccessor (&Node::m_applications), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
124 |
MakeObjectVectorChecker<Application> ()) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
125 |
.AddAttribute ("Id", "The id (unique integer) of this Node.", |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
126 |
TypeId::ATTR_GET, // allow only getting it. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
127 |
UintegerValue (0), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
128 |
MakeUintegerAccessor (&Node::m_id), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
129 |
MakeUintegerChecker<uint32_t> ()) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
130 |
; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
131 |
return tid; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
132 |
} |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
133 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
134 |
Consider the TypeId of an |ns3| ``Object`` class as an extended form of run time |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
135 |
type information (RTTI). The C++ language includes a simple kind of RTTI in |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
136 |
order to support ``dynamic_cast`` and ``typeid`` operators. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
137 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
138 |
The "``.SetParent<Object> ()``" call in the declaration above is used in |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
139 |
conjunction with our object aggregation mechanisms to allow safe up- and |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
140 |
down-casting in inheritance trees during ``GetObject``. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
141 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
142 |
The "``.AddConstructor<Node> ()``" call is used in conjunction with our abstract |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
143 |
object factory mechanisms to allow us to construct C++ objects without forcing a |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
144 |
user to know the concrete class of the object she is building. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
145 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
146 |
The three calls to "``.AddAttribute``" associate a given string with a strongly |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
147 |
typed value in the class. Notice that you must provide a help string which may |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
148 |
be displayed, for example, via command line processors. Each ``Attribute`` is |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
149 |
associated with mechanisms for accessing the underlying member variable in the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
150 |
object (for example, ``MakeUintegerAccessor`` tells the generic ``Attribute`` |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
151 |
code how to get to the node ID above). There are also "Checker" methods which |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
152 |
are used to validate values. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
153 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
154 |
When users want to create Nodes, they will usually call some form of |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
155 |
``CreateObject``,:: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
156 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
157 |
Ptr<Node> n = CreateObject<Node> (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
158 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
159 |
or more abstractly, using an object factory, you can create a ``Node`` object |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
160 |
without even knowing the concrete C++ type:: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
161 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
162 |
ObjectFactory factory; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
163 |
const std::string typeId = "ns3::Node''; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
164 |
factory.SetTypeId (typeId); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
165 |
Ptr<Object> node = factory.Create <Object> (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
166 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
167 |
Both of these methods result in fully initialized attributes being available |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
168 |
in the resulting ``Object`` instances. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
169 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
170 |
We next discuss how attributes (values associated with member variables or |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
171 |
functions of the class) are plumbed into the above TypeId. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
172 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
173 |
Attribute Overview |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
174 |
****************** |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
175 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
176 |
The goal of the attribute system is to organize the access of |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
177 |
internal member objects of a simulation. This goal arises because, |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
178 |
typically in simulation, users will cut and paste/modify existing |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
179 |
simulation scripts, or will use higher-level simulation constructs, |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
180 |
but often will be interested in studying or tracing particular |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
181 |
internal variables. For instance, use cases such as: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
182 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
183 |
* "I want to trace the packets on the wireless interface only on the first |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
184 |
access point" |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
185 |
* "I want to trace the value of the TCP congestion window (every time it |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
186 |
changes) on a particular TCP socket" |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
187 |
* "I want a dump of all values that were used in my simulation." |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
188 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
189 |
Similarly, users may want fine-grained access to internal variables in the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
190 |
simulation, or may want to broadly change the initial value used for a |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
191 |
particular parameter in all subsequently created objects. Finally, users may |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
192 |
wish to know what variables are settable and retrievable in a simulation |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
193 |
configuration. This is not just for direct simulation interaction on the command |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
194 |
line; consider also a (future) graphical user interface that would like to be |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
195 |
able to provide a feature whereby a user might right-click on an node on the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
196 |
canvas and see a hierarchical, organized list of parameters that are settable on |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
197 |
the node and its constituent member objects, and help text and default values |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
198 |
for each parameter. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
199 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
200 |
Functional overview |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
201 |
+++++++++++++++++++ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
202 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
203 |
We provide a way for users to access values deep in the system, without having |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
204 |
to plumb accessors (pointers) through the system and walk pointer chains to get |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
205 |
to them. Consider a class DropTailQueue that has a member variable that is an |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
206 |
unsigned integer ``m_maxPackets``; this member variable controls the depth of |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
207 |
the queue. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
208 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
209 |
If we look at the declaration of DropTailQueue, we see the following::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
210 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
211 |
class DropTailQueue : public Queue { |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
212 |
public: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
213 |
static TypeId GetTypeId (void); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
214 |
... |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
215 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
216 |
private: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
217 |
std::queue<Ptr<Packet> > m_packets; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
218 |
uint32_t m_maxPackets; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
219 |
}; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
220 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
221 |
Let's consider things that a user may want to do with the value of |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
222 |
m_maxPackets: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
223 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
224 |
* Set a default value for the system, such that whenever a new DropTailQueue is |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
225 |
created, this member is initialized to that default. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
226 |
* Set or get the value on an already instantiated queue. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
227 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
228 |
The above things typically require providing Set() and Get() functions, and some |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
229 |
type of global default value. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
230 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
231 |
In the |ns3| attribute system, these value definitions and accessor functions |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
232 |
are moved into the TypeId class; e.g.::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
233 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
234 |
NS_OBJECT_ENSURE_REGISTERED (DropTailQueue); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
235 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
236 |
TypeId DropTailQueue::GetTypeId (void) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
237 |
{ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
238 |
static TypeId tid = TypeId ("ns3::DropTailQueue") |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
239 |
.SetParent<Queue> () |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
240 |
.AddConstructor<DropTailQueue> () |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
241 |
.AddAttribute ("MaxPackets", |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
242 |
"The maximum number of packets accepted by this DropTailQueue.", |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
243 |
UintegerValue (100), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
244 |
MakeUintegerAccessor (&DropTailQueue::m_maxPackets), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
245 |
MakeUintegerChecker<uint32_t> ()) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
246 |
; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
247 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
248 |
return tid; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
249 |
} |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
250 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
251 |
The AddAttribute() method is performing a number of things with this |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
252 |
value: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
253 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
254 |
* Binding the variable m_maxPackets to a string "MaxPackets" |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
255 |
* Providing a default value (100 packets) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
256 |
* Providing some help text defining the value |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
257 |
* Providing a "checker" (not used in this example) that can be used to set |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
258 |
bounds on the allowable range of values |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
259 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
260 |
The key point is that now the value of this variable and its default value are |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
261 |
accessible in the attribute namespace, which is based on strings such as |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
262 |
"MaxPackets" and TypeId strings. In the next section, we will provide an example |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
263 |
script that shows how users may manipulate these values. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
264 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
265 |
Note that initialization of the attribute relies on the macro |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
266 |
``NS_OBJECT_ENSURE_REGISTERED`` (DropTailQueue) being called; if you leave this |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
267 |
out of your new class implementation, your attributes will not be initialized |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
268 |
correctly. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
269 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
270 |
While we have described how to create attributes, we still haven't described how |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
271 |
to access and manage these values. For instance, there is no ``globals.h`` |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
272 |
header file where these are stored; attributes are stored with their classes. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
273 |
Questions that naturally arise are how do users easily learn about all of the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
274 |
attributes of their models, and how does a user access these attributes, or |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
275 |
document their values as part of the record of their simulation? |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
276 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
277 |
Default values and command-line arguments |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
278 |
+++++++++++++++++++++++++++++++++++++++++ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
279 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
280 |
Let's look at how a user script might access these values. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
281 |
This is based on the script found at ``samples/main-attribute-value.cc``, |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
282 |
with some details stripped out.:: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
283 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
284 |
// |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
285 |
// This is a basic example of how to use the attribute system to |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
286 |
// set and get a value in the underlying system; namely, an unsigned |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
287 |
// integer of the maximum number of packets in a queue |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
288 |
// |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
289 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
290 |
int |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
291 |
main (int argc, char *argv[]) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
292 |
{ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
293 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
294 |
// By default, the MaxPackets attribute has a value of 100 packets |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
295 |
// (this default can be observed in the function DropTailQueue::GetTypeId) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
296 |
// |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
297 |
// Here, we set it to 80 packets. We could use one of two value types: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
298 |
// a string-based value or a Uinteger value |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
299 |
Config::SetDefault ("ns3::DropTailQueue::MaxPackets", StringValue ("80")); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
300 |
// The below function call is redundant |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
301 |
Config::SetDefault ("ns3::DropTailQueue::MaxPackets", UintegerValue (80)); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
302 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
303 |
// Allow the user to override any of the defaults and the above |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
304 |
// SetDefaults() at run-time, via command-line arguments |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
305 |
CommandLine cmd; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
306 |
cmd.Parse (argc, argv); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
307 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
308 |
The main thing to notice in the above are the two calls to |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
309 |
``Config::SetDefault``. This is how we set the default value |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
310 |
for all subsequently instantiated DropTailQueues. We illustrate |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
311 |
that two types of Value classes, a StringValue and a UintegerValue class, |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
312 |
can be used to assign the value to the attribute named by |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
313 |
"ns3::DropTailQueue::MaxPackets". |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
314 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
315 |
Now, we will create a few objects using the low-level API; here, |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
316 |
our newly created queues will not have a m_maxPackets initialized to |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
317 |
100 packets but to 80 packets, because of what we did above with |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
318 |
default values.:: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
319 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
320 |
Ptr<Node> n0 = CreateObject<Node> (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
321 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
322 |
Ptr<PointToPointNetDevice> net0 = CreateObject<PointToPointNetDevice> (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
323 |
n0->AddDevice (net0); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
324 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
325 |
Ptr<Queue> q = CreateObject<DropTailQueue> (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
326 |
net0->AddQueue(q); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
327 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
328 |
At this point, we have created a single node (Node 0) and a single |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
329 |
PointToPointNetDevice (NetDevice 0) and added a DropTailQueue to it. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
330 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
331 |
Now, we can manipulate the MaxPackets value of the already instantiated |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
332 |
DropTailQueue. Here are various ways to do that. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
333 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
334 |
Pointer-based access |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
335 |
++++++++++++++++++++ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
336 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
337 |
We assume that a smart pointer (Ptr) to a relevant network device is in hand; in |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
338 |
the current example, it is the ``net0`` pointer. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
339 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
340 |
One way to change the value is to access a pointer to the underlying queue and |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
341 |
modify its attribute. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
342 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
343 |
First, we observe that we can get a pointer to the (base class) queue via the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
344 |
PointToPointNetDevice attributes, where it is called TxQueue:: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
345 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
346 |
PointerValue tmp; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
347 |
net0->GetAttribute ("TxQueue", tmp); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
348 |
Ptr<Object> txQueue = tmp.GetObject (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
349 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
350 |
Using the GetObject function, we can perform a safe downcast to a DropTailQueue, |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
351 |
where MaxPackets is a member:: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
352 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
353 |
Ptr<DropTailQueue> dtq = txQueue->GetObject <DropTailQueue> (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
354 |
NS_ASSERT (dtq != 0); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
355 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
356 |
Next, we can get the value of an attribute on this queue. We have introduced |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
357 |
wrapper "Value" classes for the underlying data types, similar to Java wrappers |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
358 |
around these types, since the attribute system stores values and not disparate |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
359 |
types. Here, the attribute value is assigned to a UintegerValue, and the Get() |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
360 |
method on this value produces the (unwrapped) uint32_t.:: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
361 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
362 |
UintegerValue limit; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
363 |
dtq->GetAttribute ("MaxPackets", limit); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
364 |
NS_LOG_INFO ("1. dtq limit: " << limit.Get () << " packets"); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
365 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
366 |
Note that the above downcast is not really needed; we could have done the same |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
367 |
using the Ptr<Queue> even though the attribute is a member of the subclass:: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
368 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
369 |
txQueue->GetAttribute ("MaxPackets", limit); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
370 |
NS_LOG_INFO ("2. txQueue limit: " << limit.Get () << " packets"); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
371 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
372 |
Now, let's set it to another value (60 packets):: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
373 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
374 |
txQueue->SetAttribute("MaxPackets", UintegerValue (60)); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
375 |
txQueue->GetAttribute ("MaxPackets", limit); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
376 |
NS_LOG_INFO ("3. txQueue limit changed: " << limit.Get () << " packets"); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
377 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
378 |
Namespace-based access |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
379 |
++++++++++++++++++++++ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
380 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
381 |
An alternative way to get at the attribute is to use the configuration |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
382 |
namespace. Here, this attribute resides on a known path in this namespace; this |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
383 |
approach is useful if one doesn't have access to the underlying pointers and |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
384 |
would like to configure a specific attribute with a single statement.:: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
385 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
386 |
Config::Set ("/NodeList/0/DeviceList/0/TxQueue/MaxPackets", UintegerValue (25)); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
387 |
txQueue->GetAttribute ("MaxPackets", limit); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
388 |
NS_LOG_INFO ("4. txQueue limit changed through namespace: " << |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
389 |
limit.Get () << " packets"); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
390 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
391 |
We could have also used wildcards to set this value for all nodes and all net |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
392 |
devices (which in this simple example has the same effect as the previous |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
393 |
Set()):: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
394 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
395 |
Config::Set ("/NodeList/*/DeviceList/*/TxQueue/MaxPackets", UintegerValue (15)); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
396 |
txQueue->GetAttribute ("MaxPackets", limit); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
397 |
NS_LOG_INFO ("5. txQueue limit changed through wildcarded namespace: " << |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
398 |
limit.Get () << " packets"); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
399 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
400 |
Object Name Service-based access |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
401 |
++++++++++++++++++++++++++++++++ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
402 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
403 |
Another way to get at the attribute is to use the object name service facility. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
404 |
Here, this attribute is found using a name string. This approach is useful if |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
405 |
one doesn't have access to the underlying pointers and it is difficult to |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
406 |
determine the required concrete configuration namespaced path.:: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
407 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
408 |
Names::Add ("server", serverNode); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
409 |
Names::Add ("server/eth0", serverDevice); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
410 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
411 |
... |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
412 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
413 |
Config::Set ("/Names/server/eth0/TxQueue/MaxPackets", UintegerValue (25)); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
414 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
415 |
:ref:`Object names` for a fuller treatment of the |ns3| configuration namespace. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
416 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
417 |
Setting through constructors helper classes |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
418 |
+++++++++++++++++++++++++++++++++++++++++++ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
419 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
420 |
Arbitrary combinations of attributes can be set and fetched from |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
421 |
the helper and low-level APIs; either from the constructors themselves::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
422 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
423 |
Ptr<Object> p = CreateObject<MyNewObject> ("n1", v1, "n2", v2, ...); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
424 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
425 |
or from the higher-level helper APIs, such as::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
426 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
427 |
mobility.SetPositionAllocator ("GridPositionAllocator", |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
428 |
"MinX", DoubleValue (-100.0), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
429 |
"MinY", DoubleValue (-100.0), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
430 |
"DeltaX", DoubleValue (5.0), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
431 |
"DeltaY", DoubleValue (20.0), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
432 |
"GridWidth", UintegerValue (20), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
433 |
"LayoutType", StringValue ("RowFirst")); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
434 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
435 |
Implementation details |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
436 |
++++++++++++++++++++++ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
437 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
438 |
Value classes |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
439 |
~~~~~~~~~~~~~ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
440 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
441 |
Readers will note the new FooValue classes which are subclasses of the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
442 |
AttributeValue base class. These can be thought of as an intermediate class that |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
443 |
can be used to convert from raw types to the Values that are used by the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
444 |
attribute system. Recall that this database is holding objects of many types |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
445 |
with a single generic type. Conversions to this type can either be done using an |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
446 |
intermediate class (IntegerValue, DoubleValue for "floating point") or via |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
447 |
strings. Direct implicit conversion of types to Value is not really practical. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
448 |
So in the above, users have a choice of using strings or values::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
449 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
450 |
p->Set ("cwnd", StringValue ("100")); // string-based setter |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
451 |
p->Set ("cwnd", IntegerValue (100)); // integer-based setter |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
452 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
453 |
The system provides some macros that help users declare and define |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
454 |
new AttributeValue subclasses for new types that they want to introduce into |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
455 |
the attribute system: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
456 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
457 |
* ATTRIBUTE_HELPER_HEADER |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
458 |
* ATTRIBUTE_HELPER_CPP |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
459 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
460 |
Initialization order |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
461 |
~~~~~~~~~~~~~~~~~~~~ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
462 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
463 |
Attributes in the system must not depend on the state of any other Attribute in |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
464 |
this system. This is because an ordering of Attribute initialization is not |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
465 |
specified, nor enforced, by the system. A specific example of this can be seen |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
466 |
in automated configuration programs such as :cpp:class:`ns3::ConfigStore`. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
467 |
Although a given model may arrange it so that Attributes are initialized in a |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
468 |
particular order, another automatic configurator may decide independently to |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
469 |
change Attributes in, for example, alphabetic order. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
470 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
471 |
Because of this non-specific ordering, no Attribute in the system may have any |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
472 |
dependence on any other Attribute. As a corollary, Attribute setters must never |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
473 |
fail due to the state of another Attribute. No Attribute setter may change (set) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
474 |
any other Attribute value as a result of changing its value. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
475 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
476 |
This is a very strong restriction and there are cases where Attributes must set |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
477 |
consistently to allow correct operation. To this end we do allow for consistency |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
478 |
checking *when the attribute is used* (cf. NS_ASSERT_MSG or NS_ABORT_MSG). |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
479 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
480 |
In general, the attribute code to assign values to the underlying class member |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
481 |
variables is executed after an object is constructed. But what if you need the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
482 |
values assigned before the constructor body executes, because you need them in |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
483 |
the logic of the constructor? There is a way to do this, used for example in the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
484 |
class :cpp:class:`ns3::ConfigStore`: call ``ObjectBase::ConstructSelf ()`` as |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
485 |
follows::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
486 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
487 |
ConfigStore::ConfigStore () |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
488 |
{ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
489 |
ObjectBase::ConstructSelf (AttributeList ()); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
490 |
// continue on with constructor. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
491 |
} |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
492 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
493 |
Extending attributes |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
494 |
******************** |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
495 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
496 |
The |ns3| system will place a number of internal values under the attribute |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
497 |
system, but undoubtedly users will want to extend this to pick up ones we have |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
498 |
missed, or to add their own classes to this. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
499 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
500 |
Adding an existing internal variable to the metadata system |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
501 |
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
502 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
503 |
Consider this variable in class TcpSocket::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
504 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
505 |
uint32_t m_cWnd; // Congestion window |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
506 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
507 |
Suppose that someone working with TCP wanted to get or set the value of that |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
508 |
variable using the metadata system. If it were not already provided by |ns3|, |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
509 |
the user could declare the following addition in the runtime metadata system (to |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
510 |
the TypeId declaration for TcpSocket)::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
511 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
512 |
.AddAttribute ("Congestion window", |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
513 |
"Tcp congestion window (bytes)", |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
514 |
UintegerValue (1), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
515 |
MakeUintegerAccessor (&TcpSocket::m_cWnd), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
516 |
MakeUintegerChecker<uint16_t> ()) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
517 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
518 |
Now, the user with a pointer to the TcpSocket can perform operations such as |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
519 |
setting and getting the value, without having to add these functions explicitly. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
520 |
Furthermore, access controls can be applied, such as allowing the parameter to |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
521 |
be read and not written, or bounds checking on the permissible values can be |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
522 |
applied. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
523 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
524 |
Adding a new TypeId |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
525 |
+++++++++++++++++++ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
526 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
527 |
Here, we discuss the impact on a user who wants to add a new class to |ns3|; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
528 |
what additional things must be done to hook it into this system. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
529 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
530 |
We've already introduced what a TypeId definition looks like::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
531 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
532 |
TypeId |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
533 |
RandomWalk2dMobilityModel::GetTypeId (void) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
534 |
{ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
535 |
static TypeId tid = TypeId ("ns3::RandomWalk2dMobilityModel") |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
536 |
.SetParent<MobilityModel> () |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
537 |
.SetGroupName ("Mobility") |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
538 |
.AddConstructor<RandomWalk2dMobilityModel> () |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
539 |
.AddAttribute ("Bounds", |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
540 |
"Bounds of the area to cruise.", |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
541 |
RectangleValue (Rectangle (0.0, 0.0, 100.0, 100.0)), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
542 |
MakeRectangleAccessor (&RandomWalk2dMobilityModel::m_bounds), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
543 |
MakeRectangleChecker ()) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
544 |
.AddAttribute ("Time", |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
545 |
"Change current direction and speed after moving for this delay.", |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
546 |
TimeValue (Seconds (1.0)), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
547 |
MakeTimeAccessor (&RandomWalk2dMobilityModel::m_modeTime), |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
548 |
MakeTimeChecker ()) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
549 |
// etc (more parameters). |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
550 |
; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
551 |
return tid; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
552 |
} |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
553 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
554 |
The declaration for this in the class declaration is one-line public member |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
555 |
method::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
556 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
557 |
public: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
558 |
static TypeId GetTypeId (void); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
559 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
560 |
Typical mistakes here involve: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
561 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
562 |
* Not calling the SetParent method or calling it with the wrong type |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
563 |
* Not calling the AddConstructor method of calling it with the wrong type |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
564 |
* Introducing a typographical error in the name of the TypeId in its constructor |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
565 |
* Not using the fully-qualified c++ typename of the enclosing c++ class as the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
566 |
name of the TypeId |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
567 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
568 |
None of these mistakes can be detected by the |ns3| codebase so, users |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
569 |
are advised to check carefully multiple times that they got these right. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
570 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
571 |
Adding new class type to the attribute system |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
572 |
********************************************* |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
573 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
574 |
From the perspective of the user who writes a new class in the system and wants |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
575 |
to hook it in to the attribute system, there is mainly the matter of writing the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
576 |
conversions to/from strings and attribute values. Most of this can be |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
577 |
copy/pasted with macro-ized code. For instance, consider class declaration for |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
578 |
Rectangle in the ``src/mobility/`` directory: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
579 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
580 |
Header file |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
581 |
+++++++++++ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
582 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
583 |
:: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
584 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
585 |
/** |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
586 |
* \brief a 2d rectangle |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
587 |
*/ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
588 |
class Rectangle |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
589 |
{ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
590 |
... |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
591 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
592 |
double xMin; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
593 |
double xMax; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
594 |
double yMin; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
595 |
double yMax; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
596 |
}; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
597 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
598 |
One macro call and two operators, must be added below the class declaration in |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
599 |
order to turn a Rectangle into a value usable by the ``Attribute`` system::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
600 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
601 |
std::ostream &operator << (std::ostream &os, const Rectangle &rectangle); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
602 |
std::istream &operator >> (std::istream &is, Rectangle &rectangle); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
603 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
604 |
ATTRIBUTE_HELPER_HEADER (Rectangle); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
605 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
606 |
Implementation file |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
607 |
+++++++++++++++++++ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
608 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
609 |
In the class definition (``.cc`` file), the code looks like this::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
610 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
611 |
ATTRIBUTE_HELPER_CPP (Rectangle); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
612 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
613 |
std::ostream & |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
614 |
operator << (std::ostream &os, const Rectangle &rectangle) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
615 |
{ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
616 |
os << rectangle.xMin << "|" << rectangle.xMax << "|" << rectangle.yMin << "|" |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
617 |
<< rectangle.yMax; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
618 |
return os; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
619 |
} |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
620 |
std::istream & |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
621 |
operator >> (std::istream &is, Rectangle &rectangle) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
622 |
{ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
623 |
char c1, c2, c3; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
624 |
is >> rectangle.xMin >> c1 >> rectangle.xMax >> c2 >> rectangle.yMin >> c3 |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
625 |
>> rectangle.yMax; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
626 |
if (c1 != '|' || |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
627 |
c2 != '|' || |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
628 |
c3 != '|') |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
629 |
{ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
630 |
is.setstate (std::ios_base::failbit); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
631 |
} |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
632 |
return is; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
633 |
} |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
634 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
635 |
These stream operators simply convert from a string representation of the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
636 |
Rectangle ("xMin|xMax|yMin|yMax") to the underlying Rectangle, and the modeler |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
637 |
must specify these operators and the string syntactical representation of an |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
638 |
instance of the new class. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
639 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
640 |
ConfigStore |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
641 |
*********** |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
642 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
643 |
**Feedback requested:** This is an experimental feature of |ns3|. It is found |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
644 |
in ``src/contrib`` and not in the main tree. If you like this feature and |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
645 |
would like to provide feedback on it, please email us. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
646 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
647 |
Values for |ns3| attributes can be stored in an ASCII or XML text file and |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
648 |
loaded into a future simulation. This feature is known as the |ns3| |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
649 |
ConfigStore. The ConfigStore code is in ``src/contrib/``. It is not yet |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
650 |
main-tree code, because we are seeking some user feedback and experience with |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
651 |
this. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
652 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
653 |
We can explore this system by using an example. Copy the ``csma-bridge.cc`` |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
654 |
file to the scratch directory::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
655 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
656 |
cp examples/csma-bridge.cc scratch/ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
657 |
./waf |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
658 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
659 |
Let's edit it to add the ConfigStore feature. First, add an include statement to |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
660 |
include the contrib module, and then add these lines::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
661 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
662 |
#include "contrib-module.h" |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
663 |
... |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
664 |
int main (...) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
665 |
{ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
666 |
// setup topology |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
667 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
668 |
// Invoke just before entering Simulator::Run () |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
669 |
ConfigStore config; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
670 |
config.ConfigureDefaults (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
671 |
config.ConfigureAttributes (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
672 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
673 |
Simulator::Run (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
674 |
} |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
675 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
676 |
There are three attributes that govern the behavior of the ConfigStore: "Mode", |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
677 |
"Filename", and "FileFormat". The Mode (default "None") configures whether |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
678 |
|ns3| should load configuration from a previously saved file (specify |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
679 |
"Mode=Load") or save it to a file (specify "Mode=Save"). The Filename (default |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
680 |
"") is where the ConfigStore should store its output data. The FileFormat |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
681 |
(default "RawText") governs whether the ConfigStore format is Xml or RawText |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
682 |
format. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
683 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
684 |
So, using the above modified program, try executing the following waf command |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
685 |
and :: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
686 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
687 |
./waf --command-template="%s --ns3::ConfigStore::Filename=csma-bridge-config.xml |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
688 |
--ns3::ConfigStore::Mode=Save --ns3::ConfigStore::FileFormat=Xml" --run scratch/csma-bridge |
6766 | 689 |
|
690 |
After running, you can open the csma-bridge-config.xml file and it will |
|
691 |
display the configuration that was applied to your simulation; e.g.:: |
|
692 |
||
6742
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
693 |
<?xml version="1.0" encoding="UTF-8"?> |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
694 |
<ns3> |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
695 |
<default name="ns3::V4Ping::Remote" value="102.102.102.102"/> |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
696 |
<default name="ns3::MsduStandardAggregator::MaxAmsduSize" value="7935"/> |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
697 |
<default name="ns3::EdcaTxopN::MinCw" value="31"/> |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
698 |
<default name="ns3::EdcaTxopN::MaxCw" value="1023"/> |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
699 |
<default name="ns3::EdcaTxopN::Aifsn" value="3"/> |
6751
700a92acb8ec
add back manual changes made since ns-3.9
Tom Henderson <tomh@tomh.org>
parents:
6742
diff
changeset
|
700 |
<default name="ns3::StaWifiMac::ProbeRequestTimeout" value="50000000ns"/> |
700a92acb8ec
add back manual changes made since ns-3.9
Tom Henderson <tomh@tomh.org>
parents:
6742
diff
changeset
|
701 |
<default name="ns3::StaWifiMac::AssocRequestTimeout" value="500000000ns"/> |
700a92acb8ec
add back manual changes made since ns-3.9
Tom Henderson <tomh@tomh.org>
parents:
6742
diff
changeset
|
702 |
<default name="ns3::StaWifiMac::MaxMissedBeacons" value="10"/> |
700a92acb8ec
add back manual changes made since ns-3.9
Tom Henderson <tomh@tomh.org>
parents:
6742
diff
changeset
|
703 |
<default name="ns3::StaWifiMac::ActiveProbing" value="false"/> |
6742
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
704 |
... |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
705 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
706 |
This file can be archived with your simulation script and output data. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
707 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
708 |
While it is possible to generate a sample config file and lightly edit it to |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
709 |
change a couple of values, there are cases where this process will not work |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
710 |
because the same value on the same object can appear multiple times in the same |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
711 |
automatically-generated configuration file under different configuration paths. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
712 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
713 |
As such, the best way to use this class is to use it to generate an initial |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
714 |
configuration file, extract from that configuration file only the strictly |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
715 |
necessary elements, and move these minimal elements to a new configuration file |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
716 |
which can then safely be edited and loaded in a subsequent simulation run. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
717 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
718 |
When the ConfigStore object is instantiated, its attributes Filename, Mode, and |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
719 |
FileFormat must be set, either via command-line or via program statements. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
720 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
721 |
As a more complicated example, let's assume that we want to read in a |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
722 |
configuration of defaults from an input file named "input-defaults.xml", and |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
723 |
write out the resulting attributes to a separate file called |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
724 |
"output-attributes.xml". (Note-- to get this input xml file to begin with, it |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
725 |
is sometimes helpful to run the program to generate an output xml file first, |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
726 |
then hand-edit that file and re-input it for the next simulation run).:: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
727 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
728 |
#include "contrib-module.h" |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
729 |
... |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
730 |
int main (...) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
731 |
{ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
732 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
733 |
Config::SetDefault ("ns3::ConfigStore::Filename", StringValue ("input-defaults.xml")); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
734 |
Config::SetDefault ("ns3::ConfigStore::Mode", StringValue ("Load")); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
735 |
Config::SetDefault ("ns3::ConfigStore::FileFormat", StringValue ("Xml")); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
736 |
ConfigStore inputConfig; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
737 |
inputConfig.ConfigureDefaults (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
738 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
739 |
// |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
740 |
// Allow the user to override any of the defaults and the above Bind() at |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
741 |
// run-time, via command-line arguments |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
742 |
// |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
743 |
CommandLine cmd; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
744 |
cmd.Parse (argc, argv); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
745 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
746 |
// setup topology |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
747 |
... |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
748 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
749 |
// Invoke just before entering Simulator::Run () |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
750 |
Config::SetDefault ("ns3::ConfigStore::Filename", StringValue ("output-attributes.xml")); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
751 |
Config::SetDefault ("ns3::ConfigStore::Mode", StringValue ("Save")); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
752 |
ConfigStore outputConfig; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
753 |
outputConfig.ConfigureAttributes (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
754 |
Simulator::Run (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
755 |
} |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
756 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
757 |
GTK-based ConfigStore |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
758 |
+++++++++++++++++++++ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
759 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
760 |
There is a GTK-based front end for the ConfigStore. This allows users to use a |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
761 |
GUI to access and change variables. Screenshots of this feature are available |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
762 |
in the `|ns3| Overview <http://www.nsnam.org/docs/ns-3-overview.pdf>`_ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
763 |
presentation. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
764 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
765 |
To use this feature, one must install libgtk and libgtk-dev; an example |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
766 |
Ubuntu installation command is::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
767 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
768 |
sudo apt-get install libgtk2.0-0 libgtk2.0-dev |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
769 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
770 |
To check whether it is configured or not, check the output of the |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
771 |
./waf configure step::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
772 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
773 |
---- Summary of optional NS-3 features: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
774 |
Threading Primitives : enabled |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
775 |
Real Time Simulator : enabled |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
776 |
GtkConfigStore : not enabled (library 'gtk+-2.0 >= 2.12' not found) |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
777 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
778 |
In the above example, it was not enabled, so it cannot be used until a suitable |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
779 |
version is installed and ./waf configure; ./waf is rerun. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
780 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
781 |
Usage is almost the same as the non-GTK-based version, but there |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
782 |
are no ConfigStore attributes involved::: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
783 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
784 |
// Invoke just before entering Simulator::Run () |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
785 |
GtkConfigStore config; |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
786 |
config.ConfigureDefaults (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
787 |
config.ConfigureAttributes (); |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
788 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
789 |
Now, when you run the script, a GUI should pop up, allowing you to open menus of |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
790 |
attributes on different nodes/objects, and then launch the simulation execution |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
791 |
when you are done. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
792 |
|
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
793 |
Future work |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
794 |
+++++++++++ |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
795 |
There are a couple of possible improvements: |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
796 |
* save a unique version number with date and time at start of file |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
797 |
* save rng initial seed somewhere. |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
798 |
* make each RandomVariable serialize its own initial seed and re-read it later |
a1759a95842c
convert manual to sphinx format
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
799 |
* add the default values |