A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
wifi-mac-queue.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2005, 2009 INRIA
3 * Copyright (c) 2009 MIRKO BANCHI
4 *
5 * SPDX-License-Identifier: GPL-2.0-only
6 *
7 * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
8 * Mirko Banchi <mk.banchi@gmail.com>
9 * Stefano Avallone <stavallo@unina.it>
10 */
11
12#ifndef WIFI_MAC_QUEUE_H
13#define WIFI_MAC_QUEUE_H
14
15#include "qos-utils.h"
17#include "wifi-mpdu.h"
18
19#include "ns3/queue.h"
20
21#include <functional>
22#include <optional>
23#include <unordered_map>
24
25namespace ns3
26{
27
29
30// The following explicit template instantiation declaration prevents modules
31// including this header file from implicitly instantiating Queue<WifiMpdu>.
32// This would cause python examples using wifi to crash at runtime with the
33// following error message: "Trying to allocate twice the same UID:
34// ns3::Queue<WifiMpdu>"
36
37/**
38 * @ingroup wifi
39 *
40 * This queue implements the timeout procedure described in
41 * (Section 9.19.2.6 "Retransmit procedures" paragraph 6; IEEE 802.11-2012).
42 *
43 * When a packet is received by the MAC, to be sent to the PHY,
44 * it is queued in the internal queue after being tagged by the
45 * current time.
46 *
47 * When a packet is dequeued, the queue checks its timestamp
48 * to verify whether or not it should be dropped. If
49 * dot11EDCATableMSDULifetime has elapsed, it is dropped.
50 * Otherwise, it is returned to the caller.
51 *
52 * Compiling python bindings fails if the namespace (ns3) is not
53 * specified for WifiMacQueueContainerT.
54 */
56{
57 public:
58 /**
59 * @brief Get the type ID.
60 * @return the object TypeId
61 */
62 static TypeId GetTypeId();
63
64 /**
65 * Constructor
66 *
67 * @param ac the Access Category of the packets stored in this queue
68 */
70
71 ~WifiMacQueue() override;
72
73 /// allow the usage of iterators and const iterators
79
80 /**
81 * Get the Access Category of the packets stored in this queue
82 *
83 * @return the Access Category of the packets stored in this queue
84 */
85 AcIndex GetAc() const;
86
87 /**
88 * Set the wifi MAC queue scheduler
89 *
90 * @param scheduler the wifi MAC queue scheduler
91 */
93
94 /**
95 * Set the maximum delay before the packet is discarded.
96 *
97 * @param delay the maximum delay
98 */
99 void SetMaxDelay(Time delay);
100 /**
101 * Return the maximum delay before the packet is discarded.
102 *
103 * @return the maximum delay
104 */
105 Time GetMaxDelay() const;
106
107 /**
108 * Enqueue the given Wifi MAC queue item at the <i>end</i> of the queue.
109 *
110 * @param item the Wifi MAC queue item to be enqueued at the end
111 * @return true if success, false if the packet has been dropped
112 */
113 bool Enqueue(Ptr<WifiMpdu> item) override;
114 /**
115 * Dequeue the packet in the front of the queue.
116 *
117 * @return the packet
118 */
119 Ptr<WifiMpdu> Dequeue() override;
120 /**
121 * Dequeue the given MPDUs if they are stored in this queue.
122 *
123 * @param mpdus the given MPDUs
124 */
125 void DequeueIfQueued(const std::list<Ptr<const WifiMpdu>>& mpdus);
126 /**
127 * Peek the packet in the front of the queue. The packet is not removed.
128 *
129 * @return the packet
130 */
131 Ptr<const WifiMpdu> Peek() const override;
132 /**
133 * Peek the packet in the front of the queue for transmission on the given
134 * link (if any). The packet is not removed.
135 *
136 * @param linkId the ID of the link onto which we can transmit a packet
137 * @return the packet
138 */
139 Ptr<WifiMpdu> Peek(std::optional<uint8_t> linkId) const;
140 /**
141 * Search and return, if present in the queue, the first packet having the
142 * receiver address equal to <i>dest</i>, and TID equal to <i>tid</i>.
143 * If <i>item</i> is not a null pointer, the search starts from the packet
144 * following <i>item</i> in the queue; otherwise, the search starts from the
145 * head of the queue. This method does not remove the packet from the queue.
146 * It is typically used by ns3::QosTxop in order to perform correct MSDU aggregation
147 * (A-MSDU).
148 *
149 * @param tid the given TID
150 * @param dest the given destination
151 * @param item the item after which the search starts from
152 *
153 * @return the peeked packet or nullptr if no packet was found
154 */
156 Mac48Address dest,
157 Ptr<const WifiMpdu> item = nullptr) const;
158 /**
159 * Search and return the first packet present in the container queue identified
160 * by the given queue ID. If <i>item</i> is a null pointer, the search starts from
161 * the head of the container queue; MPDUs with expired lifetime at the head of the
162 * container queue are ignored (and moved to the container queue storing MPDUs with
163 * expired lifetime). If <i>item</i> is not a null pointer, the search starts from
164 * the packet following <i>item</i> in the container queue (and we do not check for
165 * expired lifetime because we assume that a previous call was made with a null
166 * pointer as argument, which removed the MPDUs with expired lifetime).
167 *
168 * @param queueId the given queue ID
169 * @param item the item after which the search starts from
170 * @return the peeked packet or nullptr if no packet was found
171 */
173 Ptr<const WifiMpdu> item = nullptr) const;
174
175 /**
176 * Return first available packet for transmission on the given link. If <i>item</i>
177 * is not a null pointer, the search starts from the packet following <i>item</i>
178 * in the queue; otherwise, the search starts from the head of the queue.
179 * The packet is not removed from queue.
180 *
181 * @param linkId the ID of the given link
182 * @param item the item after which the search starts from
183 *
184 * @return the peeked packet or nullptr if no packet was found
185 */
186 Ptr<WifiMpdu> PeekFirstAvailable(uint8_t linkId, Ptr<const WifiMpdu> item = nullptr) const;
187 /**
188 * Remove the packet in the front of the queue.
189 *
190 * @return the packet
191 */
192 Ptr<WifiMpdu> Remove() override;
193 /**
194 * Remove the given item from the queue and return the item following the
195 * removed one, if any, or a null pointer otherwise. If <i>removeExpired</i> is
196 * true, all the items in the queue from the head to the given position are
197 * removed if their lifetime expired.
198 *
199 * @param item the item to be removed
200 * @return the removed item
201 */
203
204 /**
205 * Flush the queue.
206 */
207 void Flush();
208
209 /**
210 * Replace the given current item with the given new item. Actually, the current
211 * item is dequeued and the new item is enqueued in its place. In this way,
212 * statistics about queue size (in terms of bytes) are correctly updated.
213 *
214 * @param currentItem the given current item
215 * @param newItem the given new item
216 */
217 void Replace(Ptr<const WifiMpdu> currentItem, Ptr<WifiMpdu> newItem);
218
219 /**
220 * Get the number of MPDUs currently stored in the container queue identified
221 * by the given queue ID.
222 *
223 * @param queueId the given queue ID
224 * @return the number of MPDUs currently stored in the container queue
225 */
226 uint32_t GetNPackets(const WifiContainerQueueId& queueId) const;
227
228 /**
229 * Get the amount of bytes currently stored in the container queue identified
230 * by the given queue ID.
231 *
232 * @param queueId the given queue ID
233 * @return the amount of bytes currently stored in the container queue
234 */
235 uint32_t GetNBytes(const WifiContainerQueueId& queueId) const;
236
237 /**
238 * Remove the given item if it has been in the queue for too long. Return true
239 * if the item is removed, false otherwise.
240 *
241 * @param item the item whose lifetime is checked
242 * @param now a copy of Simulator::Now()
243 * @return true if the item is removed, false otherwise
244 */
245 bool TtlExceeded(Ptr<const WifiMpdu> item, const Time& now);
246
247 /**
248 * Move MPDUs with expired lifetime from the container queue identified by the
249 * given queue ID to the container queue storing MPDUs with expired lifetime.
250 * Each MPDU that is found to have an expired lifetime feeds the "Expired"
251 * trace source and is notified to the scheduler.
252 * @note that such MPDUs are not removed from the WifiMacQueue (and hence are
253 * still accounted for in the overall statistics kept by the Queue base class)
254 * in order to make this method const.
255 *
256 * @param queueId the given queue ID
257 */
258 void ExtractExpiredMpdus(const WifiContainerQueueId& queueId) const;
259 /**
260 * Move MPDUs with expired lifetime from all the container queues to the
261 * container queue storing MPDUs with expired lifetime. Each MPDU that is found
262 * to have an expired lifetime feeds the "Expired" trace source and is notified
263 * to the scheduler.
264 * @note that such MPDUs are not removed from the WifiMacQueue (and hence are
265 * still accounted for in the overall statistics kept by the Queue base class)
266 * in order to make this method const.
267 */
268 void ExtractAllExpiredMpdus() const;
269 /**
270 * Remove all MPDUs with expired lifetime from this WifiMacQueue object.
271 */
272 void WipeAllExpiredMpdus();
273
274 /**
275 * Unlike the GetOriginal() method of WifiMpdu, this method returns a non-const
276 * pointer to the original copy of the given MPDU.
277 *
278 * @param mpdu the given MPDU
279 * @return the original copy of the given MPDU
280 */
282
283 /**
284 * @param mpdu the given MPDU
285 * @param linkId the ID of the given link
286 * @return the alias of the given MPDU that is inflight on the given link, if any, or
287 * a null pointer, otherwise
288 */
289 Ptr<WifiMpdu> GetAlias(Ptr<const WifiMpdu> mpdu, uint8_t linkId);
290
291 protected:
293
294 void DoDispose() override;
295
296 private:
297 /**
298 * @param mpdu the given MPDU
299 * @return the queue iterator stored by the given MPDU
300 */
302
303 /**
304 * Enqueue the given Wifi MAC queue item before the given position.
305 *
306 * @param pos the position before which the item is to be inserted
307 * @param item the Wifi MAC queue item to be enqueued
308 * @return true if success, false if the packet has been dropped
309 */
310 bool Insert(ConstIterator pos, Ptr<WifiMpdu> item);
311 /**
312 * Wrapper for the DoEnqueue method provided by the base class that additionally
313 * sets the iterator field of the item and updates internal statistics, if
314 * insertion succeeded.
315 *
316 * @param pos the position before where the item will be inserted
317 * @param item the item to enqueue
318 * @return true if success, false if the packet has been dropped.
319 */
320 bool DoEnqueue(ConstIterator pos, Ptr<WifiMpdu> item);
321 /**
322 * Wrapper for the DoDequeue method provided by the base class that additionally
323 * resets the iterator field of the dequeued items and notifies the scheduler, if
324 * any item was dequeued.
325 *
326 * @param iterators the list of iterators pointing to the items to dequeue
327 */
328 void DoDequeue(const std::list<ConstIterator>& iterators);
329 /**
330 * Wrapper for the DoRemove method provided by the base class that additionally
331 * resets the iterator field of the item and notifies the scheduleer, if an
332 * item was dropped.
333 *
334 * @param pos the position of the item to drop
335 * @return the dropped item.
336 */
338
339 Time m_maxDelay; //!< Time to live for packets in the queue
340 AcIndex m_ac; //!< the access category
341 Ptr<WifiMacQueueScheduler> m_scheduler; //!< the MAC queue scheduler
342
343 /// Traced callback: fired when a packet is dropped due to lifetime expiration
345
346 NS_LOG_TEMPLATE_DECLARE; //!< redefinition of the log component
347};
348
349} // namespace ns3
350
351#endif /* WIFI_MAC_QUEUE_H */
an EUI-48 address
Smart pointer class similar to boost::intrusive_ptr.
Definition ptr.h:66
bool IsEmpty() const
Definition queue.cc:71
Template class for packet Queues.
Definition queue.h:257
const ns3::WifiMacQueueContainer & GetContainer() const
Definition queue.h:493
ns3::WifiMacQueueContainer::iterator Iterator
Definition queue.h:310
ns3::WifiMacQueueContainer::const_iterator ConstIterator
Definition queue.h:308
Simulation virtual time values and global simulation resolution.
Definition nstime.h:94
Forward calls to a chain of Callback.
a unique identifier for an interface.
Definition type-id.h:49
Class for the container used by WifiMacQueue.
Time m_maxDelay
Time to live for packets in the queue.
void Replace(Ptr< const WifiMpdu > currentItem, Ptr< WifiMpdu > newItem)
Replace the given current item with the given new item.
Ptr< WifiMpdu > PeekByQueueId(const WifiContainerQueueId &queueId, Ptr< const WifiMpdu > item=nullptr) const
Search and return the first packet present in the container queue identified by the given queue ID.
Ptr< WifiMpdu > Remove() override
Remove the packet in the front of the queue.
Ptr< WifiMacQueueScheduler > m_scheduler
the MAC queue scheduler
NS_LOG_TEMPLATE_DECLARE
redefinition of the log component
AcIndex GetAc() const
Get the Access Category of the packets stored in this queue.
bool Insert(ConstIterator pos, Ptr< WifiMpdu > item)
Enqueue the given Wifi MAC queue item before the given position.
void ExtractExpiredMpdus(const WifiContainerQueueId &queueId) const
Move MPDUs with expired lifetime from the container queue identified by the given queue ID to the con...
bool Enqueue(Ptr< WifiMpdu > item) override
Enqueue the given Wifi MAC queue item at the end of the queue.
Ptr< const WifiMpdu > Peek() const override
Peek the packet in the front of the queue.
Iterator GetIt(Ptr< const WifiMpdu > mpdu) const
bool TtlExceeded(Ptr< const WifiMpdu > item, const Time &now)
Remove the given item if it has been in the queue for too long.
void WipeAllExpiredMpdus()
Remove all MPDUs with expired lifetime from this WifiMacQueue object.
Ptr< WifiMpdu > Dequeue() override
Dequeue the packet in the front of the queue.
void SetScheduler(Ptr< WifiMacQueueScheduler > scheduler)
Set the wifi MAC queue scheduler.
void SetMaxDelay(Time delay)
Set the maximum delay before the packet is discarded.
void DoDispose() override
Destructor implementation.
Ptr< WifiMpdu > GetAlias(Ptr< const WifiMpdu > mpdu, uint8_t linkId)
Ptr< WifiMpdu > DoRemove(ConstIterator pos)
Wrapper for the DoRemove method provided by the base class that additionally resets the iterator fiel...
Ptr< WifiMpdu > GetOriginal(Ptr< WifiMpdu > mpdu)
Unlike the GetOriginal() method of WifiMpdu, this method returns a non-const pointer to the original ...
WifiMacQueue(AcIndex ac=AC_UNDEF)
Constructor.
uint32_t GetNBytes(const WifiContainerQueueId &queueId) const
Get the amount of bytes currently stored in the container queue identified by the given queue ID.
Ptr< WifiMpdu > PeekFirstAvailable(uint8_t linkId, Ptr< const WifiMpdu > item=nullptr) const
Return first available packet for transmission on the given link.
void DequeueIfQueued(const std::list< Ptr< const WifiMpdu > > &mpdus)
Dequeue the given MPDUs if they are stored in this queue.
TracedCallback< Ptr< const WifiMpdu > > m_traceExpired
Traced callback: fired when a packet is dropped due to lifetime expiration.
bool DoEnqueue(ConstIterator pos, Ptr< WifiMpdu > item)
Wrapper for the DoEnqueue method provided by the base class that additionally sets the iterator field...
uint32_t GetNPackets(const WifiContainerQueueId &queueId) const
Get the number of MPDUs currently stored in the container queue identified by the given queue ID.
AcIndex m_ac
the access category
Ptr< WifiMpdu > PeekByTidAndAddress(uint8_t tid, Mac48Address dest, Ptr< const WifiMpdu > item=nullptr) const
Search and return, if present in the queue, the first packet having the receiver address equal to des...
void Flush()
Flush the queue.
void DoDequeue(const std::list< ConstIterator > &iterators)
Wrapper for the DoDequeue method provided by the base class that additionally resets the iterator fie...
void ExtractAllExpiredMpdus() const
Move MPDUs with expired lifetime from all the container queues to the container queue storing MPDUs w...
static TypeId GetTypeId()
Get the type ID.
Time GetMaxDelay() const
Return the maximum delay before the packet is discarded.
WifiMacQueueScheduler is an abstract base class defining the public interface for a wifi MAC queue sc...
WifiMpdu stores a (const) packet along with a MAC header.
Definition wifi-mpdu.h:51
AcIndex
This enumeration defines the Access Categories as an enumeration with values corresponding to the AC ...
Definition qos-utils.h:62
@ AC_UNDEF
Total number of ACs.
Definition qos-utils.h:76
Every class exported by the ns3 library is enclosed in the ns3 namespace.
std:: tuple< WifiContainerQueueType, WifiReceiverAddressType, Mac48Address, std::optional< uint8_t > > WifiContainerQueueId
Tuple (queue type, receiver address type, Address, TID) identifying a container queue.