PacketQueue

Package: inet.queueing.queue

PacketQueue

simple module

C++ definition

Implements a configurable packet queue, which is suitable for use in MAC protocols, traffic conditioning, and quality of services, among others. This is a passive component: packets are pushed into it on its input, and pulled from it on its output. This module can be used on its own, but it's also often supplemented by additional queueing components such as servers, classifiers, schedulers, multiplexers, etc. This kind of composition allows to form a larger module which can act as a packet queue with more complex behavior.

By default, this module acts as a standard FIFO queue with an infinite internal buffer. Nevertheless, it can also be configured to limit the number of packets and the total data length of packets in the internal buffer. If the queue becomes overloaded by surpassing the limits of the internal buffer, an error is raised unless a packet drop algorithm is configured.

When a packet drop algorithm is used, then one or more packets are dropped until the storage limits are met according to the dropping strategy. Packets are only dropped after the new packet has been inserted into the queue. This method allows higher priority packets to take precedence over already stored lower priority packets even if the queue is already full. If a packet dropper function is not used and any queue capacity parameter is specified then the queue provides back pressure towards its source.

The queue can also keep the packets sorted according to a comparator function. If a comparator is not configured, then packets are pushed at the back of the queue and they are kept in this order. Packets are always pulled at the front of the queue.

It's also possible to use an external buffer, which can be shared among multiple queues. In this case, the storage limits are configured on the packet buffer, which also takes care of dropping packets from either this queue or some other queues as necessary.

Some often used packet queue variants such as ~DropTailQueue are implemented as derived modules.

Some notable packet dropper functions are: ~PacketAtCollectionBeginDropper, ~PacketAtCollectionEndDropper, ~PacketWithHighestOwnerModuleIdDropper, ~PacketWithLowestOwnerModuleIdDropper.

Some notable packet comparator functions are: ~PacketUserPriorityComparator, ~PacketCreationTimeComparator, ~PacketEligibilityTimeComparator.

<b>See also:</b> ~IPacketBuffer

Inheritance diagram

The following diagram shows inheritance relationships for this type. Unresolved types are missing from the diagram.

Used in compound modules

Name Type Description
AFxyQueue compound module

This is an example queue that implements one class of the Assured Forwarding PHB group (RFC 2597).
ClientHost3 compound module (no description)
ClientHost4 compound module (no description)
ClientHost5 compound module (no description)
ClientHost6 compound module (no description)
ClientHost7 compound module (no description)
CompoundPendingQueue compound module

Implements a prioritized queue system for IEEE 802.11 MAC frames. Uses a classifier to separate incoming packets into three queues: management frames (highest priority), multicast frames (medium priority), and unicast frames (lowest priority). A priority scheduler then selects packets from these queues in order of priority.
DSQueue2 compound module

Diffserv Queue used in Experiment 2.1 - 2.4.
ExampleCompoundPriorityQueue compound module (no description)
ExampleInterface compound module (no description)
REDQueue compound module (no description)
SenderHost compound module (no description)

Used in

Name Type Description
BufferTutorialStep network (no description)
ComparatorTutorialStep network (no description)
InputQueueSwitching network (no description)
OutputQueueSwitching network (no description)
PacketQueueTutorialStep network (no description)
PriorityBufferTutorialStep network (no description)
PriorityClassifierTutorialStep network (no description)
PrioritySchedulerTutorialStep network (no description)
QueueBasedTokenGeneratorTutorialStep network (no description)
QueueFillerTutorialStep network (no description)
RedDropperTutorialStep network (no description)

Known subclasses

Name Type Description
DropHeadQueue simple module

This is a limited packet queue that drops packets at the head of the queue.
DropTailQueue simple module

A limited packet queue that drops packets at the tail of the queue.
EligibilityTimeQueue simple module

A packet queue that keeps the packets in ascending order based on the eligibility time in the attached ~EligibilityTimeTag of the packets.
InProgressQueue simple module

Specialized packet queue that only accepts packets with higher priority than those already in the queue. Unlike standard packet queues, it always returns false for canPushSomePacket() and only allows insertion of packets that compare favorably against the first packet in the queue according to the configured comparator function (see comparatorClass parameter). Useful for implementing priority-based packet processing where only higher priority packets can preempt currently queued packets.

Extends

Name Type Description
PacketQueueBase simple module

Base module for various packet queue modules which maintains a few statistics.

Parameters

Name Type Default value Description
displayStringTextFormat string "contains %p pk (%l) pushed %u\npulled %o removed %r dropped %d"

Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
packetCapacity int -1

Maximum number of packets in the queue, no limit by default
dataCapacity int -1b

Maximum total length of packets in the queue, no limit by default
dropperClass string ""

Determines which packets are dropped when the queue is overloaded, packets are not dropped by default; the parameter must be the name of a C++ class which implements the IPacketDropperFunction C++ interface and is registered via Register_Class
comparatorClass string ""

Determines the order of packets in the queue, insertion order by default; the parameter must be the name of a C++ class which implements the IPacketComparatorFunction C++ interface and is registered via Register_Class
bufferModule string ""

Relative module path to the IPacketBuffer module used by this queue, implicit buffer by default

Properties

Name Value Description
class PacketQueue
display i=block/queue
defaultStatistic queueLength:vector

Gates

Name Direction Size Description
in input
out output

Signals

Name Type Unit Description
packetRemoved inet::Packet
packetPushStarted inet::Packet
packetDropped inet::Packet
packetPushEnded inet::Packet?
packetPulled inet::Packet

Statistics

Name Title Source Record Unit Interpolation Mode Description
queueBitLength queue bit length warmup(atomic(constant0(packetPushEnded) + sum(packetLength(packetPushStarted)) - sum(packetLength(packetPulled)) - sum(packetLength(packetRemoved)) - sum(packetLength(packetDropped)))) last, max, timeavg, vector b sample-hold

the statistical value is the total bit length of all packets in the queue
queueLength queue length warmup(atomic(constant0(packetPushEnded) + count(packetPushStarted) - count(packetPulled) - count(packetRemoved) - count(packetDropped))) last, max, timeavg, vector pk sample-hold

the statistical value is the number of packets in the queue
droppedPacketsQueueOverflow dropped packets: queue overflow packetDropReasonIsQueueOverflow(packetDropped) count pk none

the statistical value is the packet that is dropped due to queue overflow
queueingTime queueing times queueingTime(packetPulled) histogram, vector s none

the statistical value is the queueing time of packets
incomingDataRate incoming datarate throughput(packetPushStarted) vector bps linear

the statistical value is the data rate of the incoming packets
flowQueueingTime flow queueing times queueingTime(demuxFlow(packetPulled)) histogram, vector s none

the statistical value is the flow specific queueing time of packets
incomingPacketLengths incoming packet lengths packetLength(packetPushStarted) sum, histogram, vector b none

the statistical value is the length of the incoming packet
flowIncomingDataRate flow specific incoming data rate throughput(flowPacketLength(demuxFlow(packetPushStarted))) vector bps linear

the statistical value is the flow specific data rate of the incoming packets
outgoingDataRate outgoing datarate throughput(packetPulled) vector bps linear

the statistical value is the data rate of the outgoing packets
outgoingPacketLengths outgoing packet lengths packetLength(packetPulled) sum, histogram, vector b none

the statistical value is the length of the outgoing packet
droppedPacketLengthsQueueOverflow dropped packet lengths: queue overflow packetLength(packetDropReasonIsQueueOverflow(packetDropped)) sum, vector b none

the statistical value is the length of the packet that is dropped due to queue overflow
flowOutgoingDataRate flow specific outgoing data rate throughput(flowPacketLength(demuxFlow(packetPulled))) vector bps linear

the statistical value is the flow specific data rate of the outgoing packets
incomingPackets incoming packets packetPushStarted count pk

the statistical value is the incoming packet
outgoingPackets outgoing packets packetPulled count pk

the statistical value is the outgoing packet

Source code

//
// Implements a configurable packet queue, which is suitable for use
// in MAC protocols, traffic conditioning, and quality of services, among others.
// This is a passive component: packets are pushed into it on its input, and pulled
// from it on its output. This module can be used on its own, but it's also often supplemented
// by additional queueing components such as servers, classifiers, schedulers,
// multiplexers, etc. This kind of composition allows to form a larger module
// which can act as a packet queue with more complex behavior.
//
// By default, this module acts as a standard FIFO queue with an infinite
// internal buffer. Nevertheless, it can also be configured to limit the number
// of packets and the total data length of packets in the internal buffer.
// If the queue becomes overloaded by surpassing the limits of the internal
// buffer, an error is raised unless a packet drop algorithm is configured.
//
// When a packet drop algorithm is used, then one or more packets are dropped
// until the storage limits are met according to the dropping strategy. Packets
// are only dropped after the new packet has been inserted into the queue. This
// method allows higher priority packets to take precedence over already stored
// lower priority packets even if the queue is already full. If a packet dropper
// function is not used and any queue capacity parameter is specified then the
// queue provides back pressure towards its source.
//
// The queue can also keep the packets sorted according to a comparator function.
// If a comparator is not configured, then packets are pushed at the back of the
// queue and they are kept in this order. Packets are always pulled at the front
// of the queue.
//
// It's also possible to use an external buffer, which can be shared among multiple
// queues. In this case, the storage limits are configured on the packet buffer,
// which also takes care of dropping packets from either this queue or some
// other queues as necessary.
//
// Some often used packet queue variants such as ~DropTailQueue are implemented
// as derived modules.
//
// Some notable packet dropper functions are: ~PacketAtCollectionBeginDropper,
// ~PacketAtCollectionEndDropper, ~PacketWithHighestOwnerModuleIdDropper,
// ~PacketWithLowestOwnerModuleIdDropper.
//
// Some notable packet comparator functions are: ~PacketUserPriorityComparator,
// ~PacketCreationTimeComparator, ~PacketEligibilityTimeComparator.
//
// @see ~IPacketBuffer
//
simple PacketQueue extends PacketQueueBase like IPacketQueue
{
    parameters:
        int packetCapacity = default(-1); // Maximum number of packets in the queue, no limit by default
        int dataCapacity @unit(b) = default(-1b); // Maximum total length of packets in the queue, no limit by default
        string dropperClass = default(""); // Determines which packets are dropped when the queue is overloaded, packets are not dropped by default; the parameter must be the name of a C++ class which implements the IPacketDropperFunction C++ interface and is registered via Register_Class
        string comparatorClass = default(""); // Determines the order of packets in the queue, insertion order by default; the parameter must be the name of a C++ class which implements the IPacketComparatorFunction C++ interface and is registered via Register_Class
        string bufferModule = default(""); // Relative module path to the IPacketBuffer module used by this queue, implicit buffer by default
        displayStringTextFormat = default("contains %p pk (%l) pushed %u\npulled %o removed %r dropped %d"); // See ~PacketQueueBase for available format specifiers
        @class(PacketQueue);
        @signal[packetPushStarted](type=inet::Packet);
        @signal[packetPushEnded](type=inet::Packet?);
        @signal[packetPulled](type=inet::Packet);
        @signal[packetRemoved](type=inet::Packet);
        @signal[packetDropped](type=inet::Packet);
        // the statistical value is the number of packets in the queue
        @statistic[queueLength](title="queue length"; source=warmup(atomic(constant0(packetPushEnded) + count(packetPushStarted) - count(packetPulled) - count(packetRemoved) - count(packetDropped))); record=last,max,timeavg,vector; unit=pk; interpolationmode=sample-hold; autoWarmupFilter=false);
        // the statistical value is the total bit length of all packets in the queue
        @statistic[queueBitLength](title="queue bit length"; source=warmup(atomic(constant0(packetPushEnded) + sum(packetLength(packetPushStarted)) - sum(packetLength(packetPulled)) - sum(packetLength(packetRemoved)) - sum(packetLength(packetDropped)))); record=last,max,timeavg,vector; unit=b; interpolationmode=sample-hold; autoWarmupFilter=false);
        // the statistical value is the queueing time of packets
        @statistic[queueingTime](title="queueing times"; source=queueingTime(packetPulled); record=histogram,vector; unit=s; interpolationmode=none);
        // the statistical value is the incoming packet
        @statistic[incomingPackets](title="incoming packets"; source=packetPushStarted; record=count; unit=pk);
        // the statistical value is the length of the incoming packet
        @statistic[incomingPacketLengths](title="incoming packet lengths"; source=packetLength(packetPushStarted); record=sum,histogram,vector; unit=b; interpolationmode=none);
        // the statistical value is the data rate of the incoming packets
        @statistic[incomingDataRate](title="incoming datarate"; source=throughput(packetPushStarted); record=vector; unit=bps; interpolationmode=linear);
        // the statistical value is the outgoing packet
        @statistic[outgoingPackets](title="outgoing packets"; source=packetPulled; record=count; unit=pk);
        // the statistical value is the length of the outgoing packet
        @statistic[outgoingPacketLengths](title="outgoing packet lengths"; source=packetLength(packetPulled); record=sum,histogram,vector; unit=b; interpolationmode=none);
        // the statistical value is the data rate of the outgoing packets
        @statistic[outgoingDataRate](title="outgoing datarate"; source=throughput(packetPulled); record=vector; unit=bps; interpolationmode=linear);
        // the statistical value is the packet that is dropped due to queue overflow
        @statistic[droppedPacketsQueueOverflow](title="dropped packets: queue overflow"; source=packetDropReasonIsQueueOverflow(packetDropped); record=count; unit=pk; interpolationmode=none);
        // the statistical value is the length of the packet that is dropped due to queue overflow
        @statistic[droppedPacketLengthsQueueOverflow](title="dropped packet lengths: queue overflow"; source=packetLength(packetDropReasonIsQueueOverflow(packetDropped)); record=sum,vector; unit=b; interpolationmode=none);
        // the statistical value is the flow specific queueing time of packets
        @statistic[flowQueueingTime](title="flow queueing times"; source=queueingTime(demuxFlow(packetPulled)); record=histogram,vector; unit=s; interpolationmode=none);
        // the statistical value is the flow specific data rate of the incoming packets
        @statistic[flowIncomingDataRate](title="flow specific incoming data rate"; source=throughput(flowPacketLength(demuxFlow(packetPushStarted))); record=vector; unit=bps; interpolationmode=linear);
        // the statistical value is the flow specific data rate of the outgoing packets
        @statistic[flowOutgoingDataRate](title="flow specific outgoing data rate"; source=throughput(flowPacketLength(demuxFlow(packetPulled))); record=vector; unit=bps; interpolationmode=linear);
        @defaultStatistic(queueLength:vector);
}
File: src/inet/queueing/queue/PacketQueue.ned

This documentation is released under the Creative Commons license