A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
node-container.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2008 INRIA
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 */
8#ifndef NODE_CONTAINER_H
9#define NODE_CONTAINER_H
10
11#include "ns3/node.h"
12
13#include <type_traits>
14#include <vector>
15
16namespace ns3
17{
18
19/**
20 * @brief keep track of a set of node pointers.
21 *
22 * Typically ns-3 helpers operate on more than one node at a time. For example
23 * a device helper may want to install devices on a large number of similar
24 * nodes. The helper Install methods usually take a NodeContainer as a
25 * parameter. NodeContainers hold the multiple Ptr<Node> which are used
26 * to refer to the nodes.
27 */
29{
30 public:
31 /// Node container iterator
32 typedef std::vector<Ptr<Node>>::const_iterator Iterator;
33
34 /**
35 * @brief Create a NodeContainer that contains a list of _all_ nodes
36 * created through NodeContainer::Create() and stored in the
37 * ns3::NodeList.
38 *
39 * Whenever a Node is created, a Ptr<Node> is added to a global list of all
40 * nodes in the system. It is sometimes useful to be able to get to all
41 * nodes in one place. This method creates a NodeContainer that is
42 * initialized to contain all of the simulation nodes,
43 *
44 * @returns a NodeContainer which contains a list of all Nodes.
45 */
46 static NodeContainer GetGlobal();
47
48 /**
49 * Create an empty NodeContainer.
50 */
52
53 /**
54 * Create a NodeContainer with exactly one node which has been previously
55 * instantiated. The single Node is specified by a smart pointer.
56 *
57 * @param node The Ptr<Node> to add to the container.
58 */
60
61 /**
62 * Create a NodeContainer with exactly one node which has been previously
63 * instantiated and assigned a name using the Object Name Service. This
64 * Node is then specified by its assigned name.
65 *
66 * @param nodeName The name of the Node Object to add to the container.
67 */
68 NodeContainer(std::string nodeName);
69
70 /**
71 * Create a NodeContainer with the requested number of Nodes.
72 *
73 * This is syntactic sugar for
74 *
75 * @code
76 * NodeContainer nodes;
77 * nodes.Create (size);
78 * // or nodes.Create (size, systemId);
79 * @endcode
80 *
81 * @param [in] n The number of nodes to create.
82 * @param [in] systemId The system id or rank associated with this node
83 */
84 explicit NodeContainer(uint32_t n, uint32_t systemId = 0);
85
86 /**
87 * Create a node container which is a concatenation of multiple input
88 * NodeContainers.
89 *
90 * @tparam Ts \deduced Template type parameter pack for the multiple
91 * NodeContainers
92 * @param nc The first NodeContainer
93 * @param args The remaining NodeContainers
94 *
95 * @note A frequently seen idiom that uses these constructors involves the
96 * implicit conversion by constructor of Ptr<Node>. When used, Ptr<Node>
97 * will be passed to this constructor instead of NodeContainer&.
98 * C++ will notice the implicit conversion path that goes through the
99 * NodeContainer (Ptr<Node> node) constructor above. Using this conversion
100 * one may optionally provide arguments of Ptr<Node> to these constructors.
101 */
102 template <typename... Ts>
103 NodeContainer(const NodeContainer& nc, Ts&&... args);
104
105 /**
106 * @brief Get an iterator which refers to the first Node in the
107 * container.
108 *
109 * Nodes can be retrieved from the container in two ways. First,
110 * directly by an index into the container, and second, using an iterator.
111 * This method is used in the iterator method and is typically used in a
112 * for-loop to run through the Nodes
113 *
114 * @code
115 * NodeContainer::Iterator i;
116 * for (i = container.Begin (); i != container.End (); ++i)
117 * {
118 * (*i)->method (); // some Node method
119 * }
120 * @endcode
121 *
122 * @returns an iterator which refers to the first Node in the container.
123 */
124 Iterator Begin() const;
125
126 /**
127 * @brief Get an iterator which indicates past-the-last Node in the
128 * container.
129 *
130 * Nodes can be retrieved from the container in two ways. First,
131 * directly by an index into the container, and second, using an iterator.
132 * This method is used in the iterator method and is typically used in a
133 * for-loop to run through the Nodes
134 *
135 * @code
136 * NodeContainer::Iterator i;
137 * for (i = container.Begin (); i != container.End (); ++i)
138 * {
139 * (*i)->method (); // some Node method
140 * }
141 * @endcode
142 *
143 * @returns an iterator which indicates an ending condition for a loop.
144 */
145 Iterator End() const;
146
147 /**
148 * @brief Get the number of Ptr<Node> stored in this container.
149 *
150 * Nodes can be retrieved from the container in two ways. First,
151 * directly by an index into the container, and second, using an iterator.
152 * This method is used in the direct method and is typically used to
153 * define an ending condition in a for-loop that runs through the stored
154 * Nodes
155 *
156 * @code
157 * uint32_t nNodes = container.GetN ();
158 * for (uint32_t i = 0; i < nNodes; ++i)
159 * {
160 * Ptr<Node> p = container.Get (i);
161 * i->method (); // some Node method
162 * }
163 * @endcode
164 *
165 * @returns the number of Ptr<Node> stored in this container.
166 */
167 uint32_t GetN() const;
168
169 /**
170 * @brief Get the Ptr<Node> stored in this container at a given
171 * index.
172 *
173 * Nodes can be retrieved from the container in two ways. First,
174 * directly by an index into the container, and second, using an iterator.
175 * This method is used in the direct method and is used to retrieve the
176 * indexed Ptr<Node>.
177 *
178 * @code
179 * uint32_t nNodes = container.GetN ();
180 * for (uint32_t i = 0; i < nNodes; ++i)
181 * {
182 * Ptr<Node> p = container.Get (i);
183 * i->method (); // some Node method
184 * }
185 * @endcode
186 *
187 * @param i the index of the requested node pointer.
188 * @returns the requested node pointer.
189 */
190 Ptr<Node> Get(uint32_t i) const;
191
192 /**
193 * @brief Create n nodes and append pointers to them to the end of this
194 * NodeContainer.
195 *
196 * Nodes are at the heart of any ns-3 simulation. One of the first tasks that
197 * any simulation needs to do is to create a number of nodes. This method
198 * automates that task.
199 *
200 * @param n The number of Nodes to create
201 */
202 void Create(uint32_t n);
203
204 /**
205 * @brief Create n nodes with specified systemId for distributed simulations
206 * and append pointers to them to the end of this NodeContainer.
207 *
208 * Nodes are at the heart of any ns-3 simulation. One of the first tasks that
209 * any simulation needs to do is to create a number of nodes. This method
210 * automates that task, and adds the ability to specify systemId for
211 * distributed simulations.
212 *
213 * @param n The number of Nodes to create
214 * @param systemId The system id or rank associated with this node
215 */
216 void Create(uint32_t n, uint32_t systemId);
217
218 /**
219 * @brief Append the contents of another NodeContainer to the end of
220 * this container.
221 *
222 * @param nc The NodeContainer to append.
223 */
224 void Add(const NodeContainer& nc);
225
226 /**
227 * @brief Append the contents of another NodeContainer to the end of
228 * this container.
229 *
230 * @tparam Ts \deduced Template type parameter pack for the multiple
231 * NodeContainer
232 * @param nc The NodeContainer to append
233 * @param args The remaining NodeContainers to append
234 */
235 template <typename... Ts>
236 void Add(const NodeContainer& nc, Ts&&... args);
237
238 /**
239 * @brief Append a single Ptr<Node> to this container.
240 *
241 * @param node The Ptr<Node> to append.
242 */
243 void Add(Ptr<Node> node);
244
245 /**
246 * @brief Append to this container the single Ptr<Node> referred to
247 * via its object name service registered name.
248 *
249 * @param nodeName The name of the Node Object to add to the container.
250 */
251 void Add(std::string nodeName);
252
253 /**
254 * @brief Return true if container contains a Node with index id
255 *
256 * @param id Node Id
257 * @return whether the NodeContainer contains a node with index id
258 */
259 bool Contains(uint32_t id) const;
260
261 private:
262 std::vector<Ptr<Node>> m_nodes; //!< Nodes smart pointers
263};
264
265} // namespace ns3
266
267///////////////////////////////////////////////////////////
268// Implementation of the templates declared above
269///////////////////////////////////////////////////////////
270
271namespace ns3
272{
273
274template <typename... Ts>
276{
277 static_assert(std::conjunction_v<std::is_convertible<Ts, NodeContainer>...>,
278 "Variable types are not convertible to NodeContainer");
279
280 Add(nc, std::forward<Ts>(args)...);
281}
282
283template <typename... Ts>
284void
285NodeContainer::Add(const NodeContainer& nc, Ts&&... args)
286{
287 static_assert(std::conjunction_v<std::is_convertible<Ts, NodeContainer>...>,
288 "Variable types are not convertible to NodeContainer");
289
290 Add(nc);
291 Add(std::forward<Ts>(args)...);
292}
293
294} // namespace ns3
295
296#endif /* NODE_CONTAINER_H */
keep track of a set of node pointers.
std::vector< Ptr< Node > >::const_iterator Iterator
Node container iterator.
Iterator End() const
Get an iterator which indicates past-the-last Node in the container.
std::vector< Ptr< Node > > m_nodes
Nodes smart pointers.
uint32_t GetN() const
Get the number of Ptr<Node> stored in this container.
static NodeContainer GetGlobal()
Create a NodeContainer that contains a list of all nodes created through NodeContainer::Create() and ...
void Create(uint32_t n)
Create n nodes and append pointers to them to the end of this NodeContainer.
bool Contains(uint32_t id) const
Return true if container contains a Node with index id.
void Add(const NodeContainer &nc)
Append the contents of another NodeContainer to the end of this container.
Iterator Begin() const
Get an iterator which refers to the first Node in the container.
NodeContainer()
Create an empty NodeContainer.
Ptr< Node > Get(uint32_t i) const
Get the Ptr<Node> stored in this container at a given index.
Smart pointer class similar to boost::intrusive_ptr.
Every class exported by the ns3 library is enclosed in the ns3 namespace.