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
28class WifiMacQueueScheduler;
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>"
35extern template class Queue<WifiMpdu, ns3::WifiMacQueueContainer>;
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
74 using Queue<WifiMpdu, WifiMacQueueContainer>::ConstIterator;
75 using Queue<WifiMpdu, WifiMacQueueContainer>::Iterator;
76 using Queue<WifiMpdu, WifiMacQueueContainer>::IsEmpty;
77 using Queue<WifiMpdu, WifiMacQueueContainer>::GetNPackets;
78 using Queue<WifiMpdu, WifiMacQueueContainer>::GetNBytes;
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 */
92 void SetScheduler(Ptr<WifiMacQueueScheduler> scheduler);
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 */
155 Ptr<WifiMpdu> PeekByTidAndAddress(uint8_t tid,
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 */
172 Ptr<WifiMpdu> PeekByQueueId(const WifiContainerQueueId& queueId,
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 */
281 Ptr<WifiMpdu> GetOriginal(Ptr<WifiMpdu> mpdu);
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:
292 using Queue<WifiMpdu, WifiMacQueueContainer>::GetContainer;
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 */
301 Iterator GetIt(Ptr<const WifiMpdu> mpdu) const;
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 */
337 Ptr<WifiMpdu> DoRemove(ConstIterator pos);
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.
Template class for packet Queues.
Definition queue.h:257
ns3::WifiMacQueueContainer::iterator Iterator
Definition queue.h:310
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:48
Class for the container used by WifiMacQueue.
This queue implements the timeout procedure described in (Section 9.19.2.6 "Retransmit procedures" pa...
Time m_maxDelay
Time to live for packets in the queue.
Ptr< WifiMacQueueScheduler > m_scheduler
the MAC queue scheduler
NS_LOG_TEMPLATE_DECLARE
redefinition of the log component
TracedCallback< Ptr< const WifiMpdu > > m_traceExpired
Traced callback: fired when a packet is dropped due to lifetime expiration.
AcIndex m_ac
the access category
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.