IOPacketQueue

Inherits from
OSObject
Availability
Available in OS X v10.0 and later.
Declared in
IOPacketQueue.h

Overview

Implements a bounded FIFO queue of mbuf packets.

Packets are removed from the head of the queue (dequeue), and new packets are added to the tail of the queue (enqueue). A spinlock is used to synchronize access to the queue between methods that have a "lock" prefix.

Tasks

Miscellaneous

Instance Methods

dequeue

Removes a single packet from the head of the queue.

virtual mbuf_t dequeue();
Return Value

Returns a packet removed from the head of the queue, or NULL if the queue was empty.

dequeueAll

Removes all packets from the queue and returns the head of the packet chain.

virtual mbuf_t dequeueAll();
Return Value

Returns the head of a packet chain linking all packets that were held in the queue, or NULL if the queue was empty.

Discussion

The size of the queue is cleared to zero.

enqueue(IOPacketQueue *)

Removes all packets from the specified queue, and adds them to the tail of this queue.

virtual bool enqueue( IOPacketQueue *queue);
Parameters
queue

The source IOPacketQueue object containing the packets to be transferred.

Return Value

Always returns true.

enqueue(mbuf_t)

Adds a chain of packets to the tail of the queue.

virtual bool enqueue( mbuf_t m);
Parameters
m

A chain of packets to add to the tail of the queue.

Return Value

Returns true on success, or false to indicate over-capacity and refusal to accept the packet chain provided.

Discussion

Packets are not added if the size of the queue has reached its capacity.

enqueueWithDrop

Adds a chain of packets to the tail of the queue.

virtual UInt32 enqueueWithDrop( mbuf_t m);
Parameters
m

A chain of packets to add to the tail of the queue.

Return Value

Returns the number of packets dropped and freed by the queue.

Discussion

Packets are dropped if the size of the queue has reached its capacity.

flush

Frees all packets currently held in the queue and releases them back to the free mbuf pool.

virtual UInt32 flush();
Return Value

Returns the number of packets freed.

Discussion

The size of the queue is cleared to zero.

free

Frees the IOPacketQueue object.

virtual void free();
Discussion

All packets held by the queue are released back to the free pool, resource are deallocated, then super::free() is called.

getCapacity

Gets the current capacity of the queue.

virtual UInt32 getCapacity() const;
Return Value

Returns the current queue capacity.

getSize

Gets the size of the queue.

virtual UInt32 getSize() const;
Return Value

Returns the number of packets currently held by the queue.

initWithCapacity

Initializes an IOPacketQueue object.

virtual bool initWithCapacity( UInt32 capacity = IOPacketQueueDefaultCapacity);
Parameters
capacity

The initial capacity of the queue. Can be later changed by calling the setCapacity() method.

Return Value

Returns true if initialized successfully, false otherwise.

Discussion

This method initializes an IOPacketQueue object with the given capacity.

lockDequeue

Removes a single packet from the head of a synchronized queue.

virtual mbuf_t lockDequeue();
Return Value

Returns a packet removed from the head of the queue, or NULL if the queue was empty.

Discussion

A spinlock is used to synchronize access to the queue.

lockDequeueAll

Removes all packets from a synchronized queue and returns the head of the packet chain.

virtual mbuf_t lockDequeueAll();
Return Value

Returns the head of a packet chain linking all packets that were held in the queue, or NULL if the queue was empty.

Discussion

The size of the queue is cleared to zero. A spinlock is used to synchronize access to the queue.

lockEnqueue

Adds a chain of packets to the tail of a synchronized queue.

virtual bool lockEnqueue( mbuf_t m);
Parameters
m

A chain of packets to add to the tail of the queue.

Return Value

Returns true on success, or false to indicate over-capacity and refusal to accept the packet chain provided.

Discussion

Packets are not added if the size of the queue has reached its capacity. A spinlock is used to synchronize access to the queue.

lockEnqueueWithDrop

Adds a chain of packets to the tail of a synchronized queue.

virtual UInt32 lockEnqueueWithDrop( mbuf_t m);
Parameters
m

A chain of packets to add to the tail of the queue.

Return Value

Returns the number of packets dropped and freed by the queue.

Discussion

Packets are dropped if the size of the queue has reached its capacity. A spinlock is used to synchronize access to the queue.

lockFlush

Frees all packets currently held in a synchronized queue and releases them back to the free mbuf pool.

virtual UInt32 lockFlush();
Return Value

Returns the number of packets freed.

Discussion

The size of the queue is cleared to zero. A spinlock is used to synchronize access to the queue.

lockPrepend

Adds a chain of packets to the head of a synchronized queue.

virtual void lockPrepend( mbuf_t m);
Parameters
m

A chain of packets to add to the head of the queue.

Return Value

Always returns true.

Discussion

A spinlock is used to synchronize access to the queue.

peek

Examines the packet at the head of the queue without removing it from the queue.

virtual const mbuf_t peek() const;
Return Value

Returns the packet at the head of the queue.

Discussion

A following call to peek() or dequeue() will return the same packet. The caller must never modify the mbuf packet returned.

prepend(IOPacketQueue *)

Removes all packets from the specified queue, and adds them to the head of this queue.

virtual void prepend( IOPacketQueue *queue);
Parameters
queue

The source IOPacketQueue object containing the packets to be transferred.

prepend(mbuf_t)

Adds a chain of packets to the head of the queue.

virtual void prepend( mbuf_t m);
Parameters
m

A chain of packets to add to the head of the queue.

setCapacity

Changes the capacity of the queue.

virtual bool setCapacity( UInt32 capacity);
Parameters
capacity

The new capacity.

Return Value

Returns true if the new capacity was accepted, false otherwise.

withCapacity

Factory method that constructs and initializes an IOPacketQueue object.

static IOPacketQueue * withCapacity( UInt32 capacity = IOPacketQueueDefaultCapacity);
Parameters
capacity

The initial capacity of the queue object. Can be later changed by calling the setCapacity() method.

Return Value

Returns an IOPacketQueue instance on success, or 0 otherwise.

Constants

IOPacketQueueDefaultCapacity
static const UInt32 IOPacketQueueDefaultCapacity = 100;

Describes the default capacity of the queue object.

The capacity is only observed by the enqueue() method. Therefore, it is possible for the size of the queue to exceed its capacity when other methods, such as prepend(), are used to add packets to the queue.

Instance Variables

reserved

ExpansionData *_reserved;

Reserved for future use. (Internal use only)

See Also

_reserved

ExpansionData *_reserved;

Reserved for future use. (Internal use only)

See Also