A Discrete-Event Network Simulator
Home
Tutorials ▼
English
Documentation ▼
Installation
Manual
Models
Contributing
Wiki
Development ▼
API Docs
Issue Tracker
Merge Requests
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
"
16
#include "
wifi-mac-queue-container.h
"
17
#include "
wifi-mpdu.h
"
18
19
#include "ns3/queue.h"
20
21
#include <functional>
22
#include <optional>
23
#include <unordered_map>
24
25
namespace
ns3
26
{
27
28
class
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>"
35
extern
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
*/
55
class
WifiMacQueue
:
public
Queue<WifiMpdu, ns3::WifiMacQueueContainer>
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
*/
69
WifiMacQueue
(
AcIndex
ac =
AC_UNDEF
);
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
*/
202
Ptr<WifiMpdu>
Remove(
Ptr<const WifiMpdu>
item);
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
344
TracedCallback<Ptr<const WifiMpdu>
>
m_traceExpired
;
345
346
NS_LOG_TEMPLATE_DECLARE
;
//!< redefinition of the log component
347
};
348
349
}
// namespace ns3
350
351
#endif
/* WIFI_MAC_QUEUE_H */
ns3::Mac48Address
an EUI-48 address
Definition
mac48-address.h:35
ns3::Ptr
Smart pointer class similar to boost::intrusive_ptr.
Definition
mpi-test-fixtures.h:37
ns3::Queue
Template class for packet Queues.
Definition
queue.h:257
ns3::Queue< WifiMpdu, ns3::WifiMacQueueContainer >::Iterator
ns3::WifiMacQueueContainer::iterator Iterator
Definition
queue.h:310
ns3::Time
Simulation virtual time values and global simulation resolution.
Definition
nstime.h:94
ns3::TracedCallback
Forward calls to a chain of Callback.
Definition
traced-callback.h:43
ns3::TypeId
a unique identifier for an interface.
Definition
type-id.h:48
ns3::WifiMacQueueContainer
Class for the container used by WifiMacQueue.
Definition
wifi-mac-queue-container.h:103
ns3::WifiMacQueue
This queue implements the timeout procedure described in (Section 9.19.2.6 "Retransmit procedures" pa...
Definition
wifi-mac-queue.h:56
ns3::WifiMacQueue::m_maxDelay
Time m_maxDelay
Time to live for packets in the queue.
Definition
wifi-mac-queue.h:339
ns3::WifiMacQueue::m_scheduler
Ptr< WifiMacQueueScheduler > m_scheduler
the MAC queue scheduler
Definition
wifi-mac-queue.h:341
ns3::WifiMacQueue::NS_LOG_TEMPLATE_DECLARE
NS_LOG_TEMPLATE_DECLARE
redefinition of the log component
Definition
wifi-mac-queue.h:346
ns3::WifiMacQueue::m_traceExpired
TracedCallback< Ptr< const WifiMpdu > > m_traceExpired
Traced callback: fired when a packet is dropped due to lifetime expiration.
Definition
wifi-mac-queue.h:344
ns3::WifiMacQueue::m_ac
AcIndex m_ac
the access category
Definition
wifi-mac-queue.h:340
ns3::WifiMpdu
WifiMpdu stores a (const) packet along with a MAC header.
Definition
wifi-mpdu.h:51
uint32_t
ns3::AcIndex
AcIndex
This enumeration defines the Access Categories as an enumeration with values corresponding to the AC ...
Definition
qos-utils.h:62
ns3::AC_UNDEF
@ AC_UNDEF
Total number of ACs.
Definition
qos-utils.h:76
ns3
Every class exported by the ns3 library is enclosed in the ns3 namespace.
ns3::WifiContainerQueueId
std:: tuple< WifiContainerQueueType, WifiReceiverAddressType, Mac48Address, std::optional< uint8_t > > WifiContainerQueueId
Tuple (queue type, receiver address type, Address, TID) identifying a container queue.
Definition
wifi-mac-queue-container.h:67
qos-utils.h
wifi-mac-queue-container.h
wifi-mpdu.h
src
wifi
model
wifi-mac-queue.h
Generated on Fri Nov 8 2024 13:59:08 for ns-3 by
1.11.0