A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
wifi-mac-queue-scheduler.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_SCHEDULER_H
10#define WIFI_MAC_QUEUE_SCHEDULER_H
11
12#include "qos-utils.h"
14
15#include "ns3/object.h"
16
17#include <bitset>
18#include <optional>
19
20namespace ns3
21{
22
23class WifiMpdu;
24class WifiMac;
25
26/**
27 * @ingroup wifi
28 *
29 * Enumeration of the reasons to block container queues.
30 */
40
41/**
42 * @brief Stream insertion operator.
43 *
44 * @param os the stream
45 * @param reason the reason to block container queues
46 * @returns a reference to the stream
47 */
48inline std::ostream&
49operator<<(std::ostream& os, WifiQueueBlockedReason reason)
50{
51 switch (reason)
52 {
54 return (os << "WAITING_ADDBA_RESP");
56 return (os << "POWER_SAVE_MODE");
58 return (os << "USING_OTHER_EMLSR_LINK");
60 return (os << "WAITING_EMLSR_TRANSITION_DELAY");
62 return (os << "TID_NOT_MAPPED");
64 return (os << "REASONS_COUNT");
65 default:
66 NS_ABORT_MSG("Unknown queue blocked reason");
67 return (os << "unknown");
68 }
69}
70
71/**
72 * @ingroup wifi
73 *
74 * WifiMacQueueScheduler is an abstract base class defining the public interface
75 * for a wifi MAC queue scheduler.
76 */
78{
79 public:
80 /**
81 * @brief Get the type ID.
82 * @return the object TypeId
83 */
84 static TypeId GetTypeId();
85
86 /**
87 * Set the wifi MAC.
88 *
89 * @param mac the wifi MAC
90 */
91 virtual void SetWifiMac(Ptr<WifiMac> mac);
92
93 /**
94 * Get the next queue to serve, which is guaranteed to contain at least an MPDU whose lifetime
95 * has not expired. Queues containing MPDUs that cannot be sent over the given link, if any, or
96 * on any link, otherwise, are ignored if and only if <i>skipBlockedQueues</i> is true.
97 *
98 * @param ac the Access Category that we want to serve
99 * @param linkId the ID of the link on which MPDUs contained in the returned queue must be
100 * allowed to be sent
101 * @param skipBlockedQueues whether queues containing MPDUs that cannot be sent over the given
102 * link, if any, or on any link, otherwise, must be ignored
103 * @return the ID of the selected container queue (if any)
104 */
105 virtual std::optional<WifiContainerQueueId> GetNext(AcIndex ac,
106 std::optional<uint8_t> linkId,
107 bool skipBlockedQueues = true) = 0;
108 /**
109 * Get the next queue to serve after the given one. The returned queue is guaranteed to contain
110 * at least an MPDU whose lifetime has not expired. Queues containing MPDUs that cannot be sent
111 * over the given link, if any, or on any link, otherwise, are ignored if and only if
112 * <i>skipBlockedQueues</i> is true.
113 *
114 * @param ac the Access Category that we want to serve
115 * @param linkId the ID of the link on which MPDUs contained in the returned queue must be
116 * allowed to be sent
117 * @param prevQueueId the ID of the container queue served previously
118 * @param skipBlockedQueues whether queues containing MPDUs that cannot be sent over the given
119 * link, if any, or on any link, otherwise, must be ignored
120 * @return the ID of the selected container queue (if any)
121 */
122 virtual std::optional<WifiContainerQueueId> GetNext(AcIndex ac,
123 std::optional<uint8_t> linkId,
124 const WifiContainerQueueId& prevQueueId,
125 bool skipBlockedQueues = true) = 0;
126
127 /**
128 * Get the list of the IDs of the links the given MPDU (belonging to the given
129 * Access Category) can be sent over.
130 *
131 * @param ac the given Access Category
132 * @param mpdu the given MPDU
133 * @param ignoredReasons list of reasons for blocking a link that are ignored
134 * @return the list of the IDs of the links the given MPDU can be sent over
135 */
136 virtual std::list<uint8_t> GetLinkIds(
137 AcIndex ac,
139 const std::list<WifiQueueBlockedReason>& ignoredReasons = {}) = 0;
140
141 /**
142 * Block the given set of links for the container queues of the given types and
143 * Access Category that hold frames having the given Receiver Address (RA),
144 * Transmitter Address (TA) and TID (if needed) for the given reason, such that
145 * frames in these queues are not transmitted on the given set of links.
146 *
147 * @param reason the reason for blocking the queues
148 * @param ac the given Access Category
149 * @param types the types of the queues to block
150 * @param rxAddress the Receiver Address (RA) of the frames
151 * @param txAddress the Transmitter Address (TA) of the frames
152 * @param tids the TIDs optionally identifying the queues to block
153 * @param linkIds set of links to block (empty to block all setup links)
154 */
156 AcIndex ac,
157 const std::list<WifiContainerQueueType>& types,
158 const Mac48Address& rxAddress,
159 const Mac48Address& txAddress,
160 const std::set<uint8_t>& tids = {},
161 const std::set<uint8_t>& linkIds = {}) = 0;
162 /**
163 * Unblock the given set of links for the container queues of the given types and
164 * Access Category that hold frames having the given Receiver Address (RA),
165 * Transmitter Address (TA) and TID (if needed) for the given reason, such that
166 * frames in these queues can be transmitted on the given set of links.
167 *
168 * @param reason the reason for unblocking the queues
169 * @param ac the given Access Category
170 * @param types the types of the queues to unblock
171 * @param rxAddress the Receiver Address (RA) of the frames
172 * @param txAddress the Transmitter Address (TA) of the frames
173 * @param tids the TIDs optionally identifying the queues to unblock
174 * @param linkIds set of links to unblock (empty to unblock all setup links)
175 */
177 AcIndex ac,
178 const std::list<WifiContainerQueueType>& types,
179 const Mac48Address& rxAddress,
180 const Mac48Address& txAddress,
181 const std::set<uint8_t>& tids = {},
182 const std::set<uint8_t>& linkIds = {}) = 0;
183
184 /**
185 * Block the given set of links for all the container queues for the given reason.
186 *
187 * @param reason the reason for blocking the queues
188 * @param linkIds set of links to block (empty to block all setup links)
189 */
191 const std::set<uint8_t>& linkIds = {}) = 0;
192
193 /**
194 * Unblock the given set of links for all the container queues for the given reason.
195 *
196 * @param reason the reason for unblocking the queues
197 * @param linkIds set of links to unblock (empty to unblock all setup links)
198 */
200 const std::set<uint8_t>& linkIds = {}) = 0;
201
202 /**
203 * Return whether all the container queues are blocked for the given link for the given
204 * reason, if different than REASONS_COUNT, or for any reason, otherwise.
205 *
206 * @param linkId the ID of the given link
207 * @param reason the reason to check (if different than REASONS_COUNT)
208 * @return whether all the container queues are blocked for the given link
209 */
211 uint8_t linkId,
213
214 /// Bitset identifying the reasons to block individual links for a container queue
215 using Mask = std::bitset<static_cast<std::size_t>(WifiQueueBlockedReason::REASONS_COUNT)>;
216
217 /**
218 * Get the mask associated with the given container queue indicating whether the given link
219 * is blocked and for which reason, provided that the given container queue exists and has
220 * a mask for the given link.
221 *
222 * @param ac the given Access Category
223 * @param queueId the ID of the given container queue
224 * @param linkId the ID of the given link
225 * @return the mask associated with the given container queue for the given link
226 */
227 virtual std::optional<Mask> GetQueueLinkMask(AcIndex ac,
228 const WifiContainerQueueId& queueId,
229 uint8_t linkId) = 0;
230
231 /**
232 * Check whether an MPDU has to be dropped before enqueuing the given MPDU.
233 *
234 * @param ac the Access Category of the MPDU being enqueued
235 * @param mpdu the MPDU to enqueue
236 * @return a pointer to the MPDU to drop, if any, or a null pointer, otherwise
237 */
239 /**
240 * Notify the scheduler that the given MPDU has been enqueued by the given Access
241 * Category. The container queue in which the MPDU has been enqueued must be
242 * assigned a priority value.
243 *
244 * @param ac the Access Category of the enqueued MPDU
245 * @param mpdu the enqueued MPDU
246 */
247 virtual void NotifyEnqueue(AcIndex ac, Ptr<WifiMpdu> mpdu) = 0;
248 /**
249 * Notify the scheduler that the given list of MPDUs have been dequeued by the
250 * given Access Category. The container queues which became empty after dequeuing
251 * the MPDUs are removed from the sorted list of queues.
252 *
253 * @param ac the Access Category of the dequeued MPDUs
254 * @param mpdus the list of dequeued MPDUs
255 */
256 virtual void NotifyDequeue(AcIndex ac, const std::list<Ptr<WifiMpdu>>& mpdus) = 0;
257 /**
258 * Notify the scheduler that the given list of MPDUs have been removed by the
259 * given Access Category. The container queues which became empty after removing
260 * the MPDUs are removed from the sorted list of queues.
261 *
262 * @param ac the Access Category of the removed MPDUs
263 * @param mpdus the list of removed MPDUs
264 */
265 virtual void NotifyRemove(AcIndex ac, const std::list<Ptr<WifiMpdu>>& mpdus) = 0;
266
267 protected:
268 void DoDispose() override;
269
270 /**
271 * Get the wifi MAC.
272 *
273 * @return the wifi MAC
274 */
275 Ptr<WifiMac> GetMac() const;
276
277 private:
278 Ptr<WifiMac> m_mac; //!< MAC layer
279};
280
281} // namespace ns3
282
283#endif /* WIFI_MAC_QUEUE_SCHEDULER_H */
an EUI-48 address
A base class which provides memory management and object aggregation.
Definition object.h:78
Smart pointer class similar to boost::intrusive_ptr.
a unique identifier for an interface.
Definition type-id.h:49
WifiMacQueueScheduler is an abstract base class defining the public interface for a wifi MAC queue sc...
virtual void NotifyRemove(AcIndex ac, const std::list< Ptr< WifiMpdu > > &mpdus)=0
Notify the scheduler that the given list of MPDUs have been removed by the given Access Category.
virtual bool GetAllQueuesBlockedOnLink(uint8_t linkId, WifiQueueBlockedReason reason=WifiQueueBlockedReason::REASONS_COUNT)=0
Return whether all the container queues are blocked for the given link for the given reason,...
virtual void SetWifiMac(Ptr< WifiMac > mac)
Set the wifi MAC.
Ptr< WifiMac > GetMac() const
Get the wifi MAC.
virtual void UnblockAllQueues(WifiQueueBlockedReason reason, const std::set< uint8_t > &linkIds={})=0
Unblock the given set of links for all the container queues for the given reason.
virtual void UnblockQueues(WifiQueueBlockedReason reason, AcIndex ac, const std::list< WifiContainerQueueType > &types, const Mac48Address &rxAddress, const Mac48Address &txAddress, const std::set< uint8_t > &tids={}, const std::set< uint8_t > &linkIds={})=0
Unblock the given set of links for the container queues of the given types and Access Category that h...
std::bitset< static_cast< std::size_t >(WifiQueueBlockedReason::REASONS_COUNT)> Mask
Bitset identifying the reasons to block individual links for a container queue.
virtual std::optional< WifiContainerQueueId > GetNext(AcIndex ac, std::optional< uint8_t > linkId, bool skipBlockedQueues=true)=0
Get the next queue to serve, which is guaranteed to contain at least an MPDU whose lifetime has not e...
virtual void BlockQueues(WifiQueueBlockedReason reason, AcIndex ac, const std::list< WifiContainerQueueType > &types, const Mac48Address &rxAddress, const Mac48Address &txAddress, const std::set< uint8_t > &tids={}, const std::set< uint8_t > &linkIds={})=0
Block the given set of links for the container queues of the given types and Access Category that hol...
virtual std::list< uint8_t > GetLinkIds(AcIndex ac, Ptr< const WifiMpdu > mpdu, const std::list< WifiQueueBlockedReason > &ignoredReasons={})=0
Get the list of the IDs of the links the given MPDU (belonging to the given Access Category) can be s...
virtual Ptr< WifiMpdu > HasToDropBeforeEnqueue(AcIndex ac, Ptr< WifiMpdu > mpdu)=0
Check whether an MPDU has to be dropped before enqueuing the given MPDU.
virtual void NotifyDequeue(AcIndex ac, const std::list< Ptr< WifiMpdu > > &mpdus)=0
Notify the scheduler that the given list of MPDUs have been dequeued by the given Access Category.
virtual std::optional< Mask > GetQueueLinkMask(AcIndex ac, const WifiContainerQueueId &queueId, uint8_t linkId)=0
Get the mask associated with the given container queue indicating whether the given link is blocked a...
virtual void NotifyEnqueue(AcIndex ac, Ptr< WifiMpdu > mpdu)=0
Notify the scheduler that the given MPDU has been enqueued by the given Access Category.
void DoDispose() override
Destructor implementation.
static TypeId GetTypeId()
Get the type ID.
virtual void BlockAllQueues(WifiQueueBlockedReason reason, const std::set< uint8_t > &linkIds={})=0
Block the given set of links for all the container queues for the given reason.
virtual std::optional< WifiContainerQueueId > GetNext(AcIndex ac, std::optional< uint8_t > linkId, const WifiContainerQueueId &prevQueueId, bool skipBlockedQueues=true)=0
Get the next queue to serve after the given one.
#define NS_ABORT_MSG(msg)
Unconditional abnormal program termination with a message.
Definition abort.h:38
WifiQueueBlockedReason
Enumeration of the reasons to block container queues.
AcIndex
This enumeration defines the Access Categories as an enumeration with values corresponding to the AC ...
Definition qos-utils.h:62
Every class exported by the ns3 library is enclosed in the ns3 namespace.
std::ostream & operator<<(std::ostream &os, const Angles &a)
Definition angles.cc:148
std::tuple< WifiContainerQueueType, WifiRcvAddr, Mac48Address, std::optional< uint8_t > > WifiContainerQueueId
Tuple (queue type, receiver address type, Address, TID) identifying a container queue.