A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
pyviz.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2008 INESC Porto
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * C++ helper functions for use by the python visualizer (for things
7 * Python is too slow at).
8 *
9 * Author: Gustavo Carneiro <gjc@inescporto.pt>
10 */
11#ifndef NS3_PYVIZ_H
12#define NS3_PYVIZ_H
13
14#include "ns3/channel.h"
15#include "ns3/event-id.h"
16#include "ns3/ipv4-header.h"
17#include "ns3/ipv4-l3-protocol.h"
18#include "ns3/mac48-address.h"
19#include "ns3/node.h"
20#include "ns3/nstime.h"
21#include "ns3/packet.h"
22
23#include <map>
24#include <set>
25
26namespace ns3
27{
28
29/**
30 * \ingroup visualizer
31 *
32 * \brief helper class to be used by the visualizer
33 * \internal
34 *
35 * This class is not meant to be used by simulations. It is only
36 * meant to be used by the visualizer tool (PyViz). The only reason
37 * it is public is because Python bindings for it are needed,
38 * otherwise it should be considered private.
39 **/
40class PyViz
41{
42 public:
43 PyViz();
44 ~PyViz();
45
46 /**
47 * Register drop trace path function
48 * \param tracePath the path to trace
49 */
50 void RegisterDropTracePath(const std::string& tracePath);
51
52 /**
53 * Register CSMA like device function
54 * \param deviceTypeName the device type name
55 */
56 void RegisterCsmaLikeDevice(const std::string& deviceTypeName);
57 /**
58 * Register WIFI like device function
59 * \param deviceTypeName the device type name
60 */
61 void RegisterWifiLikeDevice(const std::string& deviceTypeName);
62 /**
63 * Register point to point like device function
64 * \param deviceTypeName the device type name
65 */
66 void RegisterPointToPointLikeDevice(const std::string& deviceTypeName);
67
68 /**
69 * Run simulation until a given (simulated, absolute) time is reached
70 * \param time the run time
71 */
72 void SimulatorRunUntil(Time time);
73
74 /**
75 * Pause function
76 * \param message the pause message
77 */
78 static void Pause(const std::string& message);
79 /**
80 * Get pause message function
81 * \returns the pause message
82 */
83 std::vector<std::string> GetPauseMessages() const;
84
85 /// TransmissionSample structure
87 {
88 Ptr<Node> transmitter; ///< transmitter
89 Ptr<Node> receiver; ///< NULL if broadcast
90 Ptr<Channel> channel; ///< channel
91 uint32_t bytes; ///< bytes
92 };
93
94 typedef std::vector<TransmissionSample>
95 TransmissionSampleList; ///< TransmissionSampleList typedef
96 /**
97 * Get transmission samples
98 * \returns the transmission sample list
99 */
101
102 /// PacketDropSample structure
104 {
105 Ptr<Node> transmitter; ///< transmitter
106 uint32_t bytes; ///< bytes
107 };
108
109 typedef std::vector<PacketDropSample> PacketDropSampleList; ///< PacketDropSampleList typedef
110 /**
111 * Get packet drop samples
112 * \returns the packet drop sample list
113 */
115
116 /// PacketSample structure
118 {
119 Time time; ///< time
120 Ptr<Packet> packet; ///< packet
122 };
123
124 /// TxPacketSample structure
126 {
128 };
129
130 /// RxPacketSample structure
132 {
134 };
135
136 /// LastPacketsSample structure
138 {
139 std::vector<RxPacketSample> lastReceivedPackets; ///< last received packets
140 std::vector<TxPacketSample> lastTransmittedPackets; ///< last transmitted packets
141 std::vector<PacketSample> lastDroppedPackets; ///< last dropped packets
142 };
143
144 /**
145 * Get last packets function
146 * \param nodeId the node ID
147 * \returns the last packets
148 */
150
151 /**
152 * Set nodes of interest function
153 * \param nodes the collection of nodes
154 */
155 void SetNodesOfInterest(std::set<uint32_t> nodes);
156
157 /// NetDeviceStatistics structure
159 {
160 /// constructor
168
169 uint64_t transmittedBytes; ///< transmitted bytes
170 uint64_t receivedBytes; ///< received bytes
171 uint32_t transmittedPackets; ///< transmitted packets
172 uint32_t receivedPackets; ///< received packets
173 };
174
175 /// NodeStatistics structure
177 {
178 uint32_t nodeId; ///< node ID
179 std::vector<NetDeviceStatistics> statistics; ///< statistics
180 };
181
182 /**
183 * Get node statistics
184 * \returns the node statistics
185 */
186 std::vector<NodeStatistics> GetNodesStatistics() const;
187
188 /// PacketCaptureMode enumeration
190 {
191 PACKET_CAPTURE_DISABLED = 1, // packet capture is disabled
192 PACKET_CAPTURE_FILTER_HEADERS_OR, // packet capture if any of the indicated headers is
193 // present
194 PACKET_CAPTURE_FILTER_HEADERS_AND, // packet capture if all of the indicated headers are
195 // present
196 };
197
198 /// PacketCaptureOptions structure
200 {
201 std::set<TypeId> headers; ///< headers
202 uint32_t numLastPackets; ///< num last packets
204 };
205
206 /**
207 * Set packet capture options function
208 * \param nodeId the node ID
209 * \param options the capture options
210 */
212
213 // Yes, I know, this is just a utility function, not really related to the class in any way.
214 /**
215 * Utility function - clips a line to a bounding box.
216 * \param [in] boundsX1 Bounding box, minimum X coord
217 * \param [in] boundsY1 Bounding box, minimum Y coord
218 * \param [in] boundsX2 Bounding box, maximum X coord
219 * \param [in] boundsY2 Bounding box, maximum Y coord
220 * \param [in,out] lineX1 Line, minimum X coord (any on input, clipped to the bounding box
221 * on output)
222 * \param [in,out] lineY1 Line, minimum Y coord (any on input, clipped to the bounding box
223 * on output)
224 * \param [in,out] lineX2 Line, maximum X coord (any on input, clipped to the bounding box
225 * on output)
226 * \param [in,out] lineY2 Line, maximum Y coord (any on input, clipped to the bounding box
227 * on output)
228 */
229 // -#- @lineX1(direction=inout); @lineY1(direction=inout); @lineX2(direction=inout);
230 // @lineY2(direction=inout) -#-
231 static void LineClipping(double boundsX1,
232 double boundsY1,
233 double boundsX2,
234 double boundsY2,
235 double& lineX1,
236 double& lineY1,
237 double& lineX2,
238 double& lineY2);
239 // Don't break the above line or pybindgen will not be able to pick up the above annotation :(
240
241 private:
242 /**
243 * Get packet capture options function
244 * \param nodeId the node ID
245 * \param outOptions the packet capture options
246 * \returns true if successful
247 */
248 bool GetPacketCaptureOptions(uint32_t nodeId, const PacketCaptureOptions** outOptions) const;
249 /**
250 * Filter packet function
251 * \param packet the packet
252 * \param options the capture options
253 * \returns true if successful
254 */
255 static bool FilterPacket(Ptr<const Packet> packet, const PacketCaptureOptions& options);
256
257 typedef std::pair<Ptr<Channel>, uint32_t> TxRecordKey; ///< TxRecordKey typedef
258
259 /// TxRecordValue structure
261 {
262 Time time; ///< time
263 Ptr<Node> srcNode; ///< source node
264 bool isBroadcast; ///< is broadcast?
265 };
266
267 /// TransmissionSampleKey structure
269 {
270 /**
271 * Less than operator
272 *
273 * \param other object to compare
274 * \return true if less than
275 */
276 bool operator<(const TransmissionSampleKey& other) const;
277 /**
278 * Equality operator
279 *
280 * \param other object to compare
281 * \return true if equal
282 */
283 bool operator==(const TransmissionSampleKey& other) const;
284 Ptr<Node> transmitter; ///< transmitter
285 Ptr<Node> receiver; ///< NULL if broadcast
286 Ptr<Channel> channel; ///< channel
287 };
288
289 /// TransmissionSampleValue structure
291 {
292 uint32_t bytes; ///< bytes
293 };
294
295 // Data
296 std::map<uint32_t, PacketCaptureOptions> m_packetCaptureOptions; ///< packet capture options
297 std::vector<std::string> m_pauseMessages; ///< pause message
298 std::map<TxRecordKey, TxRecordValue> m_txRecords; ///< transmit records
299 std::map<TransmissionSampleKey, TransmissionSampleValue>
300 m_transmissionSamples; ///< transmission samples
301 std::map<Ptr<Node>, uint32_t> m_packetDrops; ///< packet drops
302 std::set<uint32_t>
303 m_nodesOfInterest; ///< list of node IDs whose transmissions will be monitored
304 std::map<uint32_t, Time> m_packetsOfInterest; ///< list of packet UIDs that will be monitored
305 std::map<uint32_t, LastPacketsSample> m_lastPackets; ///< last packets
306 std::map<uint32_t, std::vector<NetDeviceStatistics>> m_nodesStatistics; ///< node statistics
307
308 // Trace callbacks
309 /**
310 * Network transmit common trace callback function
311 * \param context the context
312 * \param packet the packet
313 * \param destination the destination MAC address
314 */
315 void TraceNetDevTxCommon(const std::string& context,
316 Ptr<const Packet> packet,
317 const Mac48Address& destination);
318 /**
319 * Network receive common trace callback function
320 * \param context the context
321 * \param packet the packet
322 * \param source the source MAC address
323 */
324 void TraceNetDevRxCommon(const std::string& context,
325 Ptr<const Packet> packet,
326 const Mac48Address& source);
327
328 /**
329 * Wi-Fi transmit trace callback function
330 * \param context the context
331 * \param packet the packet
332 */
333 void TraceNetDevTxWifi(std::string context, Ptr<const Packet> packet);
334 /**
335 * Wi-Fi receive trace callback function
336 * \param context the context
337 * \param packet the packet
338 */
339 void TraceNetDevRxWifi(std::string context, Ptr<const Packet> packet);
340
341 /**
342 * Queue drop trace callback function
343 * \param context the context
344 * \param packet the packet
345 */
346 void TraceDevQueueDrop(std::string context, Ptr<const Packet> packet);
347 /**
348 * Ipv4 drop trace callback function
349 * \param context the context
350 * \param hdr the header
351 * \param packet the packet
352 * \param reason the drop reason
353 * \param dummy_ipv4 the dummy Ipv4
354 * \param interface the interface
355 */
356 void TraceIpv4Drop(std::string context,
357 const ns3::Ipv4Header& hdr,
358 Ptr<const Packet> packet,
360 Ptr<Ipv4> dummy_ipv4,
361 uint32_t interface);
362
363 /**
364 * CSMA transmit trace callback function
365 * \param context the context
366 * \param packet the packet
367 */
368 void TraceNetDevTxCsma(std::string context, Ptr<const Packet> packet);
369 /**
370 * CSMA receive trace callback function
371 * \param context the context
372 * \param packet the packet
373 */
374 void TraceNetDevRxCsma(std::string context, Ptr<const Packet> packet);
375 /**
376 * CSMA promiscuous receive function
377 * \param context the context
378 * \param packet the packet
379 */
380 void TraceNetDevPromiscRxCsma(std::string context, Ptr<const Packet> packet);
381
382 /**
383 * Point to point transmit trace callback function
384 * \param context the context
385 * \param packet the packet
386 */
387 void TraceNetDevTxPointToPoint(std::string context, Ptr<const Packet> packet);
388 /**
389 * Point to point receive trace callback function
390 * \param context the context
391 * \param packet the packet
392 */
393 void TraceNetDevRxPointToPoint(std::string context, Ptr<const Packet> packet);
394
395 /**
396 * WiMax transmit trace callback function
397 * \param context the context
398 * \param packet the packet
399 * \param destination the destination MAC address
400 */
401 void TraceNetDevTxWimax(std::string context,
402 Ptr<const Packet> packet,
403 const Mac48Address& destination);
404 /**
405 * WiMax transmit trace callback function
406 * \param context the context
407 * \param packet the packet
408 * \param source the source MAC address
409 */
410 void TraceNetDevRxWimax(std::string context,
411 Ptr<const Packet> packet,
412 const Mac48Address& source);
413
414 /**
415 * LTE transmit trace callback function
416 * \param context the context
417 * \param packet the packet
418 * \param destination the destination MAC address
419 */
420 void TraceNetDevTxLte(std::string context,
421 Ptr<const Packet> packet,
422 const Mac48Address& destination);
423 /**
424 * LTE receive trace callback function
425 * \param context the context
426 * \param packet the packet
427 * \param source the MAC address of the source
428 */
429 void TraceNetDevRxLte(std::string context,
430 Ptr<const Packet> packet,
431 const Mac48Address& source);
432
433 /**
434 * Find net device statistics function
435 * \param node the node
436 * \param interface the interface number
437 * \returns the device statistics
438 */
439 inline NetDeviceStatistics& FindNetDeviceStatistics(int node, int interface);
440
441 /**
442 * Do pause function
443 * \param message the pause message
444 */
445 void DoPause(const std::string& message);
446
447 bool m_stop; ///< stop?
448 Time m_runUntil; ///< run until time
449
450 /// Stop simulation callback function
452};
453
454} // namespace ns3
455
456#endif /* NS3_PYVIZ_H */
Packet header for IPv4.
Definition ipv4-header.h:23
DropReason
Reason why a packet has been dropped.
an EUI-48 address
Smart pointer class similar to boost::intrusive_ptr.
helper class to be used by the visualizer
Definition pyviz.h:41
void RegisterCsmaLikeDevice(const std::string &deviceTypeName)
Register CSMA like device function.
Definition pyviz.cc:173
void TraceNetDevRxCsma(std::string context, Ptr< const Packet > packet)
CSMA receive trace callback function.
Definition pyviz.cc:770
void SetPacketCaptureOptions(uint32_t nodeId, PacketCaptureOptions options)
Set packet capture options function.
Definition pyviz.cc:219
void TraceNetDevRxPointToPoint(std::string context, Ptr< const Packet > packet)
Point to point receive trace callback function.
Definition pyviz.cc:778
void RegisterDropTracePath(const std::string &tracePath)
Register drop trace path function.
Definition pyviz.cc:229
void RegisterWifiLikeDevice(const std::string &deviceTypeName)
Register WIFI like device function.
Definition pyviz.cc:191
std::map< uint32_t, PacketCaptureOptions > m_packetCaptureOptions
packet capture options
Definition pyviz.h:296
void TraceNetDevTxLte(std::string context, Ptr< const Packet > packet, const Mac48Address &destination)
LTE transmit trace callback function.
Definition pyviz.cc:816
std::map< uint32_t, LastPacketsSample > m_lastPackets
last packets
Definition pyviz.h:305
void SimulatorRunUntil(Time time)
Run simulation until a given (simulated, absolute) time is reached.
Definition pyviz.cc:279
bool m_stop
stop?
Definition pyviz.h:447
PacketDropSampleList GetPacketDropSamples() const
Get packet drop samples.
Definition pyviz.cc:854
void SetNodesOfInterest(std::set< uint32_t > nodes)
Set nodes of interest function.
Definition pyviz.cc:872
std::map< uint32_t, std::vector< NetDeviceStatistics > > m_nodesStatistics
node statistics
Definition pyviz.h:306
void TraceNetDevTxCsma(std::string context, Ptr< const Packet > packet)
CSMA transmit trace callback function.
Definition pyviz.cc:605
void TraceNetDevTxCommon(const std::string &context, Ptr< const Packet > packet, const Mac48Address &destination)
Network transmit common trace callback function.
Definition pyviz.cc:510
void DoPause(const std::string &message)
Do pause function.
Definition pyviz.cc:243
std::vector< NodeStatistics > GetNodesStatistics() const
Get node statistics.
Definition pyviz.cc:878
void TraceNetDevRxWimax(std::string context, Ptr< const Packet > packet, const Mac48Address &source)
WiMax transmit trace callback function.
Definition pyviz.cc:809
std::set< uint32_t > m_nodesOfInterest
list of node IDs whose transmissions will be monitored
Definition pyviz.h:303
void TraceNetDevPromiscRxCsma(std::string context, Ptr< const Packet > packet)
CSMA promiscuous receive function.
Definition pyviz.cc:784
static void Pause(const std::string &message)
Pause function.
Definition pyviz.cc:252
std::vector< std::string > m_pauseMessages
pause message
Definition pyviz.h:297
void TraceNetDevRxLte(std::string context, Ptr< const Packet > packet, const Mac48Address &source)
LTE receive trace callback function.
Definition pyviz.cc:825
void TraceNetDevTxWimax(std::string context, Ptr< const Packet > packet, const Mac48Address &destination)
WiMax transmit trace callback function.
Definition pyviz.cc:800
void TraceIpv4Drop(std::string context, const ns3::Ipv4Header &hdr, Ptr< const Packet > packet, ns3::Ipv4L3Protocol::DropReason reason, Ptr< Ipv4 > dummy_ipv4, uint32_t interface)
Ipv4 drop trace callback function.
Definition pyviz.cc:495
void TraceNetDevRxCommon(const std::string &context, Ptr< const Packet > packet, const Mac48Address &source)
Network receive common trace callback function.
Definition pyviz.cc:621
TransmissionSampleList GetTransmissionSamples() const
Get transmission samples.
Definition pyviz.cc:834
static void LineClipping(double boundsX1, double boundsY1, double boundsX2, double boundsY2, double &lineX1, double &lineY1, double &lineX2, double &lineY2)
Utility function - clips a line to a bounding box.
Definition pyviz.cc:1579
std::map< TransmissionSampleKey, TransmissionSampleValue > m_transmissionSamples
transmission samples
Definition pyviz.h:300
void TraceNetDevTxPointToPoint(std::string context, Ptr< const Packet > packet)
Point to point transmit trace callback function.
Definition pyviz.cc:613
void TraceNetDevRxWifi(std::string context, Ptr< const Packet > packet)
Wi-Fi receive trace callback function.
Definition pyviz.cc:738
NetDeviceStatistics & FindNetDeviceStatistics(int node, int interface)
Find net device statistics function.
Definition pyviz.cc:373
void TraceDevQueueDrop(std::string context, Ptr< const Packet > packet)
Queue drop trace callback function.
Definition pyviz.cc:448
std::map< TxRecordKey, TxRecordValue > m_txRecords
transmit records
Definition pyviz.h:298
std::vector< std::string > GetPauseMessages() const
Get pause message function.
Definition pyviz.cc:259
std::vector< PacketDropSample > PacketDropSampleList
PacketDropSampleList typedef.
Definition pyviz.h:109
static bool FilterPacket(Ptr< const Packet > packet, const PacketCaptureOptions &options)
Filter packet function.
Definition pyviz.cc:406
void CallbackStopSimulation()
Stop simulation callback function.
Definition pyviz.cc:268
void RegisterPointToPointLikeDevice(const std::string &deviceTypeName)
Register point to point like device function.
Definition pyviz.cc:205
std::map< Ptr< Node >, uint32_t > m_packetDrops
packet drops
Definition pyviz.h:301
LastPacketsSample GetLastPackets(uint32_t nodeId) const
Get last packets function.
Definition pyviz.cc:890
void TraceNetDevTxWifi(std::string context, Ptr< const Packet > packet)
Wi-Fi transmit trace callback function.
Definition pyviz.cc:578
bool GetPacketCaptureOptions(uint32_t nodeId, const PacketCaptureOptions **outOptions) const
Get packet capture options function.
Definition pyviz.cc:391
Time m_runUntil
run until time
Definition pyviz.h:448
std::map< uint32_t, Time > m_packetsOfInterest
list of packet UIDs that will be monitored
Definition pyviz.h:304
std::pair< Ptr< Channel >, uint32_t > TxRecordKey
TxRecordKey typedef.
Definition pyviz.h:257
std::vector< TransmissionSample > TransmissionSampleList
TransmissionSampleList typedef.
Definition pyviz.h:95
PacketCaptureMode
PacketCaptureMode enumeration.
Definition pyviz.h:190
@ PACKET_CAPTURE_FILTER_HEADERS_OR
Definition pyviz.h:192
@ PACKET_CAPTURE_DISABLED
Definition pyviz.h:191
@ PACKET_CAPTURE_FILTER_HEADERS_AND
Definition pyviz.h:194
Simulation virtual time values and global simulation resolution.
Definition nstime.h:94
NodeContainer nodes
Every class exported by the ns3 library is enclosed in the ns3 namespace.
LastPacketsSample structure.
Definition pyviz.h:138
std::vector< PacketSample > lastDroppedPackets
last dropped packets
Definition pyviz.h:141
std::vector< TxPacketSample > lastTransmittedPackets
last transmitted packets
Definition pyviz.h:140
std::vector< RxPacketSample > lastReceivedPackets
last received packets
Definition pyviz.h:139
NetDeviceStatistics structure.
Definition pyviz.h:159
uint64_t receivedBytes
received bytes
Definition pyviz.h:170
uint64_t transmittedBytes
transmitted bytes
Definition pyviz.h:169
uint32_t receivedPackets
received packets
Definition pyviz.h:172
NetDeviceStatistics()
constructor
Definition pyviz.h:161
uint32_t transmittedPackets
transmitted packets
Definition pyviz.h:171
NodeStatistics structure.
Definition pyviz.h:177
std::vector< NetDeviceStatistics > statistics
statistics
Definition pyviz.h:179
uint32_t nodeId
node ID
Definition pyviz.h:178
PacketCaptureOptions structure.
Definition pyviz.h:200
PacketCaptureMode mode
mode
Definition pyviz.h:203
uint32_t numLastPackets
num last packets
Definition pyviz.h:202
std::set< TypeId > headers
headers
Definition pyviz.h:201
PacketDropSample structure.
Definition pyviz.h:104
Ptr< Node > transmitter
transmitter
Definition pyviz.h:105
PacketSample structure.
Definition pyviz.h:118
Ptr< Packet > packet
packet
Definition pyviz.h:120
Ptr< NetDevice > device
device
Definition pyviz.h:121
RxPacketSample structure.
Definition pyviz.h:132
Mac48Address from
from
Definition pyviz.h:133
TransmissionSample structure.
Definition pyviz.h:87
Ptr< Node > transmitter
transmitter
Definition pyviz.h:88
Ptr< Channel > channel
channel
Definition pyviz.h:90
Ptr< Node > receiver
NULL if broadcast.
Definition pyviz.h:89
TransmissionSampleKey structure.
Definition pyviz.h:269
Ptr< Channel > channel
channel
Definition pyviz.h:286
bool operator==(const TransmissionSampleKey &other) const
Equality operator.
Definition pyviz.cc:365
bool operator<(const TransmissionSampleKey &other) const
Less than operator.
Definition pyviz.cc:343
Ptr< Node > transmitter
transmitter
Definition pyviz.h:284
Ptr< Node > receiver
NULL if broadcast.
Definition pyviz.h:285
TransmissionSampleValue structure.
Definition pyviz.h:291
TxPacketSample structure.
Definition pyviz.h:126
Mac48Address to
to
Definition pyviz.h:127
TxRecordValue structure.
Definition pyviz.h:261
Ptr< Node > srcNode
source node
Definition pyviz.h:263
bool isBroadcast
is broadcast?
Definition pyviz.h:264