A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
wifi-mac-queue-container.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2022 Universita' degli Studi di Napoli Federico II
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Stefano Avallone <stavallo@unina.it>
7 */
8
9#ifndef WIFI_MAC_QUEUE_CONTAINER_H
10#define WIFI_MAC_QUEUE_CONTAINER_H
11
12#include "wifi-mac-queue-elem.h"
13
14#include "ns3/deprecated.h"
15#include "ns3/mac48-address.h"
16
17#include <list>
18#include <optional>
19#include <tuple>
20#include <unordered_map>
21
22namespace ns3
23{
24
25/// enumeration of container queue types
33
34/// enumeration of frame types based on receiver address
35enum class WifiRcvAddr : uint8_t
36{
41};
42
43/**
44 * Deprecated frame types enums.
45 *
46 * Use `WifiRcvAddr` class enum values instead.
47 * @{
48 */
49NS_DEPRECATED_3_46("Use WifiRcvAddr::UNICAST instead")
50static constexpr auto WIFI_UNICAST = WifiRcvAddr::UNICAST;
51NS_DEPRECATED_3_46("Use WifiRcvAddr::BROADCAST instead")
52static constexpr auto WIFI_BROADCAST = WifiRcvAddr::BROADCAST;
53NS_DEPRECATED_3_46("Use WifiRcvAddr::GROUPCAST instead")
54static constexpr auto WIFI_GROUPCAST = WifiRcvAddr::GROUPCAST;
55/**@}*/
56
57/**
58 * Tuple (queue type, receiver address type, Address, TID) identifying a container queue.
59 *
60 * @note that Address has a different meaning depending on container queue type:
61 *
62 * - for container queue types holding unicast frames, Address is the Receiver Address (RA)
63 * of the frames stored in the queue. For 11be MLDs, it is expected that:
64 * + the RA of unicast management frames are link addresses (indicating the link on which
65 * they must be sent)
66 * + the RA of unicast QoS data frames are MLD addresses (indicating that they can be sent
67 * on any link)
68 * + if the RA of a unicast control frame is a link address, that control frame can only be
69 * sent on the corresponding link; if the RA is an MLD address, that control frame can be
70 * sent on any link
71 *
72 * - for container queue types holding broadcast frames, Address is the Transmitter Address (TA)
73 * of the frames stored in the queue. For 11be MLDs, it is expected that:
74 * + the TA of broadcast management frames are link addresses (indicating the link on which
75 * they must be sent)
76 * + the TA of broadcast QoS data frames are MLD addresses (indicating that they can be sent
77 * on any link)
78 * + if the TA of a broadcast control frame is a link address, that control frame can only be
79 * sent on the corresponding link; if the TA is an MLD address, that control frame can be
80 * sent on any link
81 *
82 * The TID is only specified for container queue types holding QoS data frames.
83 */
85 std::tuple<WifiContainerQueueType, WifiRcvAddr, Mac48Address, std::optional<uint8_t>>;
86
87} // namespace ns3
88
89/****************************************************
90 * Global Functions (outside namespace ns3)
91 ***************************************************/
92
93/**
94 * @ingroup wifi
95 * Hashing functor taking a QueueId and returning a @c std::size_t.
96 * For use with `unordered_map` and `unordered_set`.
97 */
98template <>
99struct std::hash<ns3::WifiContainerQueueId>
100{
101 /**
102 * The functor.
103 * @param queueId The QueueId value to hash.
104 * @return the hash
105 */
106 std::size_t operator()(ns3::WifiContainerQueueId queueId) const;
107};
108
109namespace ns3
110{
111
112/**
113 * @ingroup wifi
114 * Class for the container used by WifiMacQueue
115 *
116 * This container holds multiple container queues organized in an hash table
117 * whose keys are WifiContainerQueueId tuples identifying the container queues.
118 */
120{
121 public:
122 /// Type of a queue held by the container
123 using ContainerQueue = std::list<WifiMacQueueElem>;
124 /// iterator over elements in a container queue
125 using iterator = ContainerQueue::iterator;
126 /// const iterator over elements in a container queue
127 using const_iterator = ContainerQueue::const_iterator;
128
129 /**
130 * Erase all elements from the container.
131 */
132 void clear();
133
134 /**
135 * Insert the given item at the specified location in the container.
136 *
137 * @param pos iterator before which the item will be inserted
138 * @param item the item to insert in the container
139 * @return iterator pointing to the inserted item
140 */
142
143 /**
144 * Erase the specified elements from the container.
145 *
146 * @param pos iterator to the element to remove
147 * @return iterator following the removed element
148 */
150
151 /**
152 * Return the WifiMpdu included in the element pointed to by the given iterator.
153 *
154 * @param it the given iterator
155 * @return the item included in the element pointed to by the given iterator
156 */
157 Ptr<WifiMpdu> GetItem(const const_iterator it) const;
158
159 /**
160 * Return the QueueId identifying the container queue in which the given MPDU is
161 * (or is to be) enqueued. Note that the given MPDU must not contain a control frame.
162 *
163 * @param mpdu the given MPDU
164 * @return the QueueId identifying the container queue in which the given MPDU
165 * is (or is to be) enqueued
166 */
168
169 /**
170 * Get a const reference to the container queue identified by the given QueueId.
171 * The container queue is created if it does not exist.
172 *
173 * @param queueId the given QueueId
174 * @return a const reference to the container queue identified by the given QueueId
175 */
176 const ContainerQueue& GetQueue(const WifiContainerQueueId& queueId) const;
177
178 /**
179 * Get the total size of the MPDUs stored in the queue identified by the given QueueId.
180 *
181 * @param queueId the given queue ID
182 * @return true if the given queue does not exist in the container or is empty,
183 * false otherwise
184 */
185 uint32_t GetNBytes(const WifiContainerQueueId& queueId) const;
186
187 /**
188 * Transfer non-inflight MPDUs with expired lifetime in the container queue identified by
189 * the given QueueId to the container queue storing MPDUs with expired lifetime.
190 *
191 * @param queueId the QueueId identifying the container queue
192 * @return the range [first, last) of iterators pointing to the MPDUs transferred
193 * to the container queue storing MPDUs with expired lifetime
194 */
195 std::pair<iterator, iterator> ExtractExpiredMpdus(const WifiContainerQueueId& queueId) const;
196 /**
197 * Transfer non-inflight MPDUs with expired lifetime in all the container queues to the
198 * container queue storing MPDUs with expired lifetime.
199 *
200 * @return the range [first, last) of iterators pointing to the MPDUs transferred
201 * to the container queue storing MPDUs with expired lifetime
202 */
203 std::pair<iterator, iterator> ExtractAllExpiredMpdus() const;
204 /**
205 * Get the range [first, last) of iterators pointing to all the MPDUs queued
206 * in the container queue storing MPDUs with expired lifetime.
207 *
208 * @return the range [first, last) of iterators pointing to all the MPDUs queued
209 * in the container queue storing MPDUs with expired lifetime
210 */
211 std::pair<iterator, iterator> GetAllExpiredMpdus() const;
212
213 private:
214 /**
215 * Transfer non-inflight MPDUs with expired lifetime in the given container queue to the
216 * container queue storing MPDUs with expired lifetime.
217 *
218 * @param queue the given container queue
219 * @return the range [first, last) of iterators pointing to the MPDUs transferred
220 * to the container queue storing MPDUs with expired lifetime
221 */
222 std::pair<iterator, iterator> DoExtractExpiredMpdus(ContainerQueue& queue) const;
223
224 mutable std::unordered_map<WifiContainerQueueId, ContainerQueue>
225 m_queues; //!< the container queues
226 mutable ContainerQueue m_expiredQueue; //!< queue storing MPDUs with expired lifetime
227 mutable std::unordered_map<WifiContainerQueueId, uint32_t>
228 m_nBytesPerQueue; //!< size in bytes of the container queues
229};
230
231} // namespace ns3
232
233#endif /* WIFI_MAC_QUEUE_CONTAINER_H */
an EUI-48 address
Smart pointer class similar to boost::intrusive_ptr.
Definition ptr.h:67
Class for the container used by WifiMacQueue.
const ContainerQueue & GetQueue(const WifiContainerQueueId &queueId) const
Get a const reference to the container queue identified by the given QueueId.
void clear()
Erase all elements from the container.
static WifiContainerQueueId GetQueueId(Ptr< const WifiMpdu > mpdu)
Return the QueueId identifying the container queue in which the given MPDU is (or is to be) enqueued.
ContainerQueue::iterator iterator
iterator over elements in a container queue
std::unordered_map< WifiContainerQueueId, uint32_t > m_nBytesPerQueue
size in bytes of the container queues
uint32_t GetNBytes(const WifiContainerQueueId &queueId) const
Get the total size of the MPDUs stored in the queue identified by the given QueueId.
Ptr< WifiMpdu > GetItem(const const_iterator it) const
Return the WifiMpdu included in the element pointed to by the given iterator.
std::pair< iterator, iterator > ExtractAllExpiredMpdus() const
Transfer non-inflight MPDUs with expired lifetime in all the container queues to the container queue ...
iterator insert(const_iterator pos, Ptr< WifiMpdu > item)
Insert the given item at the specified location in the container.
std::unordered_map< WifiContainerQueueId, ContainerQueue > m_queues
the container queues
std::list< WifiMacQueueElem > ContainerQueue
Type of a queue held by the container.
iterator erase(const_iterator pos)
Erase the specified elements from the container.
std::pair< iterator, iterator > GetAllExpiredMpdus() const
Get the range [first, last) of iterators pointing to all the MPDUs queued in the container queue stor...
ContainerQueue::const_iterator const_iterator
const iterator over elements in a container queue
ContainerQueue m_expiredQueue
queue storing MPDUs with expired lifetime
std::pair< iterator, iterator > ExtractExpiredMpdus(const WifiContainerQueueId &queueId) const
Transfer non-inflight MPDUs with expired lifetime in the container queue identified by the given Queu...
std::pair< iterator, iterator > DoExtractExpiredMpdus(ContainerQueue &queue) const
Transfer non-inflight MPDUs with expired lifetime in the given container queue to the container queue...
#define NS_DEPRECATED_3_46(msg)
Tag for things deprecated in version ns-3.46.
Definition deprecated.h:91
Every class exported by the ns3 library is enclosed in the ns3 namespace.
static constexpr auto WIFI_UNICAST
Deprecated frame types enums.
static constexpr auto WIFI_GROUPCAST
static constexpr auto WIFI_BROADCAST
WifiRcvAddr
enumeration of frame types based on receiver address
WifiContainerQueueType
enumeration of container queue types
std::tuple< WifiContainerQueueType, WifiRcvAddr, Mac48Address, std::optional< uint8_t > > WifiContainerQueueId
Tuple (queue type, receiver address type, Address, TID) identifying a container queue.
STL namespace.
std::size_t operator()(ns3::WifiContainerQueueId queueId) const
The functor.