A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
ns3::WifiTxStatsHelper Class Reference

Statistics helper for tracking outcomes of data MPDU transmissions. More...

#include "wifi-tx-stats-helper.h"

+ Collaboration diagram for ns3::WifiTxStatsHelper:

Classes

struct  MpduRecord
 Structure for recording information about an individual data MPDU transmission. More...
 
struct  TupleHash
 Hash function for the tuples used in unordered_maps. More...
 

Public Types

using CountPerNodeDevice_t
 std::unordered_map of {nodeId, deviceId} tuple to counter value
 
using CountPerNodeDeviceLink_t
 std::unordered_map of {nodeId, deviceId, linkId} tuple to counter value
 
using MpduRecordsPerNodeDevice_t
 std::unordered_map of {nodeId, deviceId} tuple to a list of MPDU records
 
using MpduRecordsPerNodeDeviceLink_t
 std::unordered_map of {nodeId, deviceId, linkId} tuple to a list of MPDU records
 
enum  MultiLinkSuccessType : uint8_t { FIRST_LINK_IN_SET , ALL_LINKS }
 When Multi-Link Operation (MLO) is used, it is possible for MPDUs to be sent on multiple links concurrently. More...
 

Public Member Functions

 WifiTxStatsHelper ()
 Default constructor; start time initialized to zero and stop time to Time::Max()
 
 WifiTxStatsHelper (Time startTime, Time stopTime)
 Construct a helper with start and stop times.
 
void Enable (const NetDeviceContainer &devices)
 Enables trace collection for all WifiNetDevices in the specified NetDeviceContainer.
 
void Enable (const NodeContainer &nodes)
 Enables trace collection for all nodes and WifiNetDevices in the specified NodeContainer.
 
Time GetDuration () const
 Return the duration since the helper was started or reset.
 
const MpduRecordsPerNodeDevice_tGetFailureRecords () const
 Return a hash map of MPDU records for failed transmissions.
 
uint64_t GetFailures () const
 Return the count of failed MPDU transmissions across all enabled devices.
 
uint64_t GetFailures (WifiMacDropReason reason) const
 Return the count of failed MPDU transmissions due to given drop reason across all enabled devices.
 
CountPerNodeDevice_t GetFailuresByNodeDevice () const
 Return the counts of failed MPDU transmissions in a hash map.
 
CountPerNodeDevice_t GetFailuresByNodeDevice (WifiMacDropReason reason) const
 Return the counts of failed MPDU transmissions due to given drop reason in a hash map.
 
uint64_t GetRetransmissions () const
 Return the count of MPDU retransmissions across all enabled devices.
 
CountPerNodeDevice_t GetRetransmissionsByNodeDevice () const
 Return the counts of MPDU retransmissions in a hash map.
 
uint64_t GetSuccesses () const
 Return the count of successful MPDU transmissions across all enabled devices.
 
CountPerNodeDevice_t GetSuccessesByNodeDevice () const
 Return the counts of successful MPDU transmissions in a hash map.
 
CountPerNodeDeviceLink_t GetSuccessesByNodeDeviceLink (WifiTxStatsHelper::MultiLinkSuccessType type=FIRST_LINK_IN_SET) const
 Return the counts of successful MPDU transmissions in a hash map.
 
const MpduRecordsPerNodeDeviceLink_t GetSuccessRecords (WifiTxStatsHelper::MultiLinkSuccessType type=FIRST_LINK_IN_SET) const
 Return a hash map of successful MPDU records.
 
void Reset ()
 Clear the data structures for all completed successful and failed MpduRecords.
 
void Start (Time startTime)
 Set the start time for statistics collection.
 
void Stop (Time stopTime)
 Set the stop time for statistics collection.
 

Private Member Functions

void NotifyAcked (uint32_t nodeId, uint32_t deviceId, Ptr< const WifiMpdu > mpdu)
 Callback for the WifiMac::AckedMpdu trace.
 
void NotifyMacDropped (uint32_t nodeId, uint32_t deviceId, WifiMacDropReason reason, Ptr< const WifiMpdu > mpdu)
 Callback for the WifiMac::DroppedMpdu trace.
 
void NotifyMacEnqueue (uint32_t nodeId, uint32_t deviceId, Ptr< const WifiMpdu > mpdu)
 Callback for the WifiMacQueue::Enqueue trace.
 
void NotifyTxStart (uint32_t nodeId, uint32_t deviceId, Ptr< const Packet > pkt, Watt_u)
 Callback for the WifiPhy::PhyTxBegin trace.
 

Private Attributes

MpduRecordsPerNodeDevice_t m_failureMap
 The nested map of failed MPDUs.
 
std::map< uint64_t, MpduRecordm_inflightMap
 In-flight MPDUs; key is a Packet UID.
 
Time m_startTime
 The start time for recording statistics.
 
Time m_stopTime {Time::Max()}
 The stop time for recording statistics.
 
MpduRecordsPerNodeDevice_t m_successMap
 The nested map of successful MPDUs.
 

Detailed Description

Statistics helper for tracking outcomes of data MPDU transmissions.

This helper may be used to track statistics of all data MPDU transmissions on a given Node, WifiNetDevice, or even link granularity (for MLO operation), including counts of the number of successfully acknowledged MPDUs, the number of retransmissions (if any) of those successfully acknowledged MPDUs, and the number of failed MPDUs (by drop reason). The helper can also be used to access timestamped data about how long the MPDU was enqueued and how long it took to complete acknowledgement (or failure) once the first transmission of it was attempted. For failed MPDUs, their WifiMacDropReason can be accessed.

Definition at line 49 of file wifi-tx-stats-helper.h.

Member Typedef Documentation

◆ CountPerNodeDevice_t

Initial value:
std::unordered_map<std::tuple<uint32_t, uint32_t>,
uint64_t,
TupleHash>

std::unordered_map of {nodeId, deviceId} tuple to counter value

Definition at line 190 of file wifi-tx-stats-helper.h.

◆ CountPerNodeDeviceLink_t

Initial value:
std::unordered_map<std::tuple<uint32_t, uint32_t, uint8_t>,
uint64_t,
TupleHash>

std::unordered_map of {nodeId, deviceId, linkId} tuple to counter value

Definition at line 185 of file wifi-tx-stats-helper.h.

◆ MpduRecordsPerNodeDevice_t

Initial value:
std::unordered_map<std::tuple<uint32_t, uint32_t>,
std::list<MpduRecord>,
TupleHash>

std::unordered_map of {nodeId, deviceId} tuple to a list of MPDU records

Definition at line 200 of file wifi-tx-stats-helper.h.

◆ MpduRecordsPerNodeDeviceLink_t

Initial value:
std::unordered_map<std::tuple<uint32_t, uint32_t, uint8_t>,
std::list<MpduRecord>,
TupleHash>

std::unordered_map of {nodeId, deviceId, linkId} tuple to a list of MPDU records

Definition at line 195 of file wifi-tx-stats-helper.h.

Member Enumeration Documentation

◆ MultiLinkSuccessType

When Multi-Link Operation (MLO) is used, it is possible for MPDUs to be sent on multiple links concurrently.

When such an MPDU is acked, a question arises as to how to count the number of successes (only one success, or success on each link). The ACK does not convey which transmission on which link triggered the event. Therefore, two policies are defined for how to count a successful event. 1) FIRST_LINK_IN_SET: Count the success on the first link of the set of in-flight links 2) ALL_LINKS: Count the success on all links in the in-flight link set

Enumerator
FIRST_LINK_IN_SET 
ALL_LINKS 

Definition at line 61 of file wifi-tx-stats-helper.h.

Constructor & Destructor Documentation

◆ WifiTxStatsHelper() [1/2]

ns3::WifiTxStatsHelper::WifiTxStatsHelper ( )

Default constructor; start time initialized to zero and stop time to Time::Max()

Definition at line 27 of file wifi-tx-stats-helper.cc.

References NS_LOG_FUNCTION.

◆ WifiTxStatsHelper() [2/2]

ns3::WifiTxStatsHelper::WifiTxStatsHelper ( Time startTime,
Time stopTime )

Construct a helper with start and stop times.

Only those MPDUs enqueued between the start and stop times will be counted.

Parameters
startTimeThe measurement start time
stopTimeThe measurement stop time

Definition at line 32 of file wifi-tx-stats-helper.cc.

References ns3::Time::As(), NS_ASSERT_MSG, NS_LOG_FUNCTION, ns3::Time::S, and stopTime.

+ Here is the call graph for this function:

Member Function Documentation

◆ Enable() [1/2]

void ns3::WifiTxStatsHelper::Enable ( const NetDeviceContainer & devices)

Enables trace collection for all WifiNetDevices in the specified NetDeviceContainer.

Parameters
devicesThe NetDeviceContainer to which traces are to be connected.

Definition at line 57 of file wifi-tx-stats-helper.cc.

References ns3::AC_BE_NQOS, ns3::DynamicCast(), ns3::MakeCallback(), NotifyAcked(), NotifyMacDropped(), NotifyMacEnqueue(), NotifyTxStart(), NS_LOG_DEBUG, NS_LOG_FUNCTION, NS_LOG_INFO, and ns3::wifiAcList.

+ Here is the call graph for this function:

◆ Enable() [2/2]

void ns3::WifiTxStatsHelper::Enable ( const NodeContainer & nodes)

Enables trace collection for all nodes and WifiNetDevices in the specified NodeContainer.

Parameters
nodesThe NodeContainer to which traces are to be connected.

Definition at line 42 of file wifi-tx-stats-helper.cc.

References ns3::NetDeviceContainer::Add(), Enable(), nodes, and NS_LOG_FUNCTION.

Referenced by WifiTxStatsHelperTest::DoRun(), Enable(), and Experiment::Run().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ GetDuration()

Time ns3::WifiTxStatsHelper::GetDuration ( ) const

Return the duration since the helper was started or reset.

Returns
The duration since the helper was started or reset

Definition at line 318 of file wifi-tx-stats-helper.cc.

References m_startTime, and ns3::Now().

+ Here is the call graph for this function:

◆ GetFailureRecords()

const WifiTxStatsHelper::MpduRecordsPerNodeDevice_t & ns3::WifiTxStatsHelper::GetFailureRecords ( ) const

Return a hash map of MPDU records for failed transmissions.

The return type is an std::unordered_map, and the keys are tuples of {node ID, device ID}. The value returned by indexing the tuple is the list of MPDU records of the MPDUs that failed.

Returns
A const reference to the hash map of MPDU records corresponding to failure

Definition at line 358 of file wifi-tx-stats-helper.cc.

References m_failureMap.

Referenced by WifiTxStatsHelperTest::CheckResults().

+ Here is the caller graph for this function:

◆ GetFailures() [1/2]

uint64_t ns3::WifiTxStatsHelper::GetFailures ( ) const

Return the count of failed MPDU transmissions across all enabled devices.

Returns
The count of all failed MPDU transmissions

Definition at line 274 of file wifi-tx-stats-helper.cc.

References m_failureMap.

Referenced by WifiTxStatsHelperTest::CheckResults().

+ Here is the caller graph for this function:

◆ GetFailures() [2/2]

uint64_t ns3::WifiTxStatsHelper::GetFailures ( WifiMacDropReason reason) const

Return the count of failed MPDU transmissions due to given drop reason across all enabled devices.

Parameters
reasonReason for dropping the MPDU
Returns
The count of all failed MPDU transmissions for the specified reason

Definition at line 285 of file wifi-tx-stats-helper.cc.

References m_failureMap, and NS_ASSERT_MSG.

◆ GetFailuresByNodeDevice() [1/2]

WifiTxStatsHelper::CountPerNodeDevice_t ns3::WifiTxStatsHelper::GetFailuresByNodeDevice ( ) const

Return the counts of failed MPDU transmissions in a hash map.

The return type is an std::unordered_map, and the keys are tuples of {node ID, device ID}. The value returned by indexing the tuple is the count of failed MPDU transmissions.

The number of failures are only stored with the granularity of per-device, since in a multi-link scenario, some retransmissions (that lead to eventual failure) may occur on different links.

Returns
A hash map with counts of MPDU failed transmissions

Definition at line 200 of file wifi-tx-stats-helper.cc.

References m_failureMap.

Referenced by WifiTxStatsHelperTest::CheckResults(), and Experiment::Run().

+ Here is the caller graph for this function:

◆ GetFailuresByNodeDevice() [2/2]

WifiTxStatsHelper::CountPerNodeDevice_t ns3::WifiTxStatsHelper::GetFailuresByNodeDevice ( WifiMacDropReason reason) const

Return the counts of failed MPDU transmissions due to given drop reason in a hash map.

Parameters
reasonReason for dropping the MPDU

The return type is an std::unordered_map, and the keys are tuples of {node ID, device ID}. The value returned by indexing the tuple is the count of failed MPDU transmissions due to the reason given.

The number of failures are only stored with the granularity of per-device, since in a multi-link scenario, some retransmissions (that lead to eventual failure) may occur on different links.

Returns
A hash map with counts of MPDU failed transmissions

Definition at line 211 of file wifi-tx-stats-helper.cc.

References m_failureMap, and NS_ASSERT_MSG.

◆ GetRetransmissions()

uint64_t ns3::WifiTxStatsHelper::GetRetransmissions ( ) const

Return the count of MPDU retransmissions across all enabled devices.

Returns
The count of all MPDU retransmissions for acked MPDUs

Definition at line 304 of file wifi-tx-stats-helper.cc.

References m_successMap.

Referenced by WifiTxStatsHelperTest::CheckResults().

+ Here is the caller graph for this function:

◆ GetRetransmissionsByNodeDevice()

WifiTxStatsHelper::CountPerNodeDevice_t ns3::WifiTxStatsHelper::GetRetransmissionsByNodeDevice ( ) const

Return the counts of MPDU retransmissions in a hash map.

The return type is an std::unordered_map, and the keys are tuples of {node ID, device ID}. The value returned by indexing the tuple is the count of MPDU retransmissions of those MPDUs that were successfully acked.

The number of retransmissions are only stored with the granularity of per-device, since in a multi-link scenario, some retransmissions may be sent on different links.

Returns
A hash map with counts of MPDU retransmissions for successful MPDUs

Definition at line 239 of file wifi-tx-stats-helper.cc.

References m_successMap.

Referenced by WifiTxStatsHelperTest::CheckResults(), and Experiment::Run().

+ Here is the caller graph for this function:

◆ GetSuccesses()

uint64_t ns3::WifiTxStatsHelper::GetSuccesses ( ) const

Return the count of successful MPDU transmissions across all enabled devices.

Returns
The count of all successful MPDU transmissions

Definition at line 263 of file wifi-tx-stats-helper.cc.

References m_successMap.

Referenced by WifiTxStatsHelperTest::CheckResults().

+ Here is the caller graph for this function:

◆ GetSuccessesByNodeDevice()

WifiTxStatsHelper::CountPerNodeDevice_t ns3::WifiTxStatsHelper::GetSuccessesByNodeDevice ( ) const

Return the counts of successful MPDU transmissions in a hash map.

The return type is an std::unordered_map, and the keys are tuples of {node ID, device ID}. The value returned by indexing the tuple is the count of successful MPDU transmissions.

If Multi-Link Operation (MLO) is configured, a variant of this method is available that returns an unordered_map indexed by a tuple that includes the Link ID, for more granular statistics reporting.

See also
GetSuccessesByNodeDeviceLink

If Multi-Link Operation (MLO) is configured, and MPDUs are sent on multiple links in parallel, this method will count one success for any such acknowledged MPDU (even if it was successfully received on more than one link).

Returns
A hash map with counts of MPDU successful transmissions

Definition at line 141 of file wifi-tx-stats-helper.cc.

References m_successMap.

Referenced by WifiTxStatsHelperTest::CheckResults(), and Experiment::Run().

+ Here is the caller graph for this function:

◆ GetSuccessesByNodeDeviceLink()

WifiTxStatsHelper::CountPerNodeDeviceLink_t ns3::WifiTxStatsHelper::GetSuccessesByNodeDeviceLink ( WifiTxStatsHelper::MultiLinkSuccessType type = FIRST_LINK_IN_SET) const

Return the counts of successful MPDU transmissions in a hash map.

Parameters
typehow the statistics handle a successful MPDU transmitted on multiple links

The return type is an std::unordered_map, and the keys are tuples of {node ID, device ID, link ID}. The value returned by indexing the tuple is the count of successful MPDU transmissions.

The link ID corresponds to the link for which the MPDU was successfully acknowledged, regardless of the links that may have been used in earlier transmissions of the MPDU.

For a similar method that does not use Link IDs in the key,

See also
GetSuccessesByNodeDevice
Returns
A hash map with counts of MPDU successful transmissions

Definition at line 152 of file wifi-tx-stats-helper.cc.

References FIRST_LINK_IN_SET, m_successMap, and NS_ASSERT_MSG.

Referenced by WifiTxStatsHelperTest::CheckResults().

+ Here is the caller graph for this function:

◆ GetSuccessRecords()

Return a hash map of successful MPDU records.

Parameters
typehow the statistics handle a successful MPDU transmitted on multiple links

The return type is an std::unordered_map, and the keys are tuples of {node ID, device ID, link ID}. The value returned by indexing the tuple is the list of MPDU records of the MPDUs that were successfully acked.

Returns
A const reference to the hash map of successful MPDU records

Definition at line 324 of file wifi-tx-stats-helper.cc.

References FIRST_LINK_IN_SET, m_successMap, and NS_ASSERT_MSG.

Referenced by WifiTxStatsHelperTest::CheckResults().

+ Here is the caller graph for this function:

◆ NotifyAcked()

void ns3::WifiTxStatsHelper::NotifyAcked ( uint32_t nodeId,
uint32_t deviceId,
Ptr< const WifiMpdu > mpdu )
private

Callback for the WifiMac::AckedMpdu trace.

Parameters
nodeIdthe Node ID triggering the trace
deviceIdthe Node ID triggering the trace
mpduThe MPDU acked

Definition at line 422 of file wifi-tx-stats-helper.cc.

References m_inflightMap, m_stopTime, m_successMap, ns3::Now(), NS_ASSERT_MSG, NS_LOG_DEBUG, NS_LOG_FUNCTION, and NS_LOG_INFO.

Referenced by Enable().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ NotifyMacDropped()

void ns3::WifiTxStatsHelper::NotifyMacDropped ( uint32_t nodeId,
uint32_t deviceId,
WifiMacDropReason reason,
Ptr< const WifiMpdu > mpdu )
private

Callback for the WifiMac::DroppedMpdu trace.

Parameters
nodeIdthe Node ID triggering the trace
deviceIdthe Node ID triggering the trace
reasonReason for dropping the MPDU
mpduThe MPDU dropped

Definition at line 455 of file wifi-tx-stats-helper.cc.

References m_failureMap, m_inflightMap, m_stopTime, ns3::Now(), NS_LOG_DEBUG, NS_LOG_FUNCTION, and NS_LOG_INFO.

Referenced by Enable().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ NotifyMacEnqueue()

void ns3::WifiTxStatsHelper::NotifyMacEnqueue ( uint32_t nodeId,
uint32_t deviceId,
Ptr< const WifiMpdu > mpdu )
private

Callback for the WifiMacQueue::Enqueue trace.

Parameters
nodeIdthe Node ID triggering the trace
deviceIdthe Node ID triggering the trace
mpduThe MPDU enqueued

Definition at line 364 of file wifi-tx-stats-helper.cc.

References m_inflightMap, ns3::WifiTxStatsHelper::MpduRecord::m_nodeId, m_stopTime, ns3::Simulator::Now(), NS_LOG_DEBUG, NS_LOG_FUNCTION, and NS_LOG_INFO.

Referenced by Enable().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ NotifyTxStart()

void ns3::WifiTxStatsHelper::NotifyTxStart ( uint32_t nodeId,
uint32_t deviceId,
Ptr< const Packet > pkt,
Watt_u  )
private

Callback for the WifiPhy::PhyTxBegin trace.

Parameters
nodeIdthe Node ID triggering the trace
deviceIdthe Node ID triggering the trace
pktThe frame being sent

Definition at line 393 of file wifi-tx-stats-helper.cc.

References m_inflightMap, m_stopTime, ns3::Now(), NS_LOG_DEBUG, NS_LOG_FUNCTION, and NS_LOG_INFO.

Referenced by Enable().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ Reset()

void ns3::WifiTxStatsHelper::Reset ( )

Clear the data structures for all completed successful and failed MpduRecords.

Definition at line 132 of file wifi-tx-stats-helper.cc.

References m_failureMap, m_startTime, m_successMap, ns3::Now(), and NS_LOG_FUNCTION.

+ Here is the call graph for this function:

◆ Start()

void ns3::WifiTxStatsHelper::Start ( Time startTime)

Set the start time for statistics collection.

No MPDUs enqueued before startTime will be included in the statistics.

Parameters
startTimeThe measurement start time

Definition at line 112 of file wifi-tx-stats-helper.cc.

References ns3::Time::As(), m_startTime, m_stopTime, ns3::Now(), NS_ASSERT_MSG, NS_LOG_FUNCTION, and ns3::Time::S.

Referenced by WifiTxStatsHelperTest::DoRun(), and Experiment::Run().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ Stop()

void ns3::WifiTxStatsHelper::Stop ( Time stopTime)

Set the stop time for statistics collection.

No MPDUs enqueued after stopTime elapses will be included in statistics. However, MPDUs that were enqueued before stopTime (and after startTime) will be included in the statistics if they are dequeued before the statistics are queried by the user.

Parameters
stopTimeThe measurement stop time

Definition at line 122 of file wifi-tx-stats-helper.cc.

References m_startTime, m_stopTime, ns3::Now(), NS_ASSERT_MSG, NS_LOG_FUNCTION, ns3::Time::S, and stopTime.

Referenced by WifiTxStatsHelperTest::DoRun(), and Experiment::Run().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

Member Data Documentation

◆ m_failureMap

MpduRecordsPerNodeDevice_t ns3::WifiTxStatsHelper::m_failureMap
private

◆ m_inflightMap

std::map<uint64_t, MpduRecord> ns3::WifiTxStatsHelper::m_inflightMap
private

In-flight MPDUs; key is a Packet UID.

Definition at line 382 of file wifi-tx-stats-helper.h.

Referenced by NotifyAcked(), NotifyMacDropped(), NotifyMacEnqueue(), and NotifyTxStart().

◆ m_startTime

Time ns3::WifiTxStatsHelper::m_startTime
private

The start time for recording statistics.

Definition at line 383 of file wifi-tx-stats-helper.h.

Referenced by GetDuration(), Reset(), Start(), and Stop().

◆ m_stopTime

Time ns3::WifiTxStatsHelper::m_stopTime {Time::Max()}
private

The stop time for recording statistics.

Definition at line 384 of file wifi-tx-stats-helper.h.

Referenced by NotifyAcked(), NotifyMacDropped(), NotifyMacEnqueue(), NotifyTxStart(), Start(), and Stop().

◆ m_successMap

MpduRecordsPerNodeDevice_t ns3::WifiTxStatsHelper::m_successMap
private

The documentation for this class was generated from the following files: