ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

IOPacketQueue

Inherits from:	OSObject
Declared In:	IOPacketQueue.h

Overview

Implements a bounded FIFO queue of mbuf packets.

Discussion

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.

Functions

dequeue: Removes a single packet from the head of the queue.
dequeueAll: Removes all packets from the queue and returns the head of the packet chain.
enqueue(IOPacketQueue *): Removes all packets from the specified queue, and adds them to the tail of this queue.
enqueue(mbuf_t): Adds a chain of packets to the tail of the queue.
enqueueWithDrop: Adds a chain of packets to the tail of the queue.
flush: Frees all packets currently held in the queue and releases them back to the free mbuf pool.
free: Frees the IOPacketQueue object.
getCapacity: Gets the current capacity of the queue.
getSize: Gets the size of the queue.
initWithCapacity: Initializes an IOPacketQueue object.
lockDequeue: Removes a single packet from the head of a synchronized queue.
lockDequeueAll: Removes all packets from a synchronized queue and returns the head of the packet chain.
lockEnqueue: Adds a chain of packets to the tail of a synchronized queue.
lockEnqueueWithDrop: Adds a chain of packets to the tail of a synchronized queue.
lockFlush: Frees all packets currently held in a synchronized queue and releases them back to the free mbuf pool.
lockPrepend: Adds a chain of packets to the head of a synchronized queue.
peek: Examines the packet at the head of the queue without removing it from the queue.
prepend(IOPacketQueue *): Removes all packets from the specified queue, and adds them to the head of this queue.
prepend(mbuf_t): Adds a chain of packets to the head of the queue.
setCapacity: Changes the capacity of the queue.
withCapacity: Factory method that constructs and initializes an IOPacketQueue object.

dequeue

Removes a single packet from the head of the queue.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

protected

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.

public

virtual UInt32 getCapacity() const;

Return Value

Returns the current queue capacity.

getSize

Gets the size of the queue.

public

virtual UInt32 getSize() const;

Return Value

Returns the number of packets currently held by the queue.

initWithCapacity

Initializes an IOPacketQueue object.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

Member Data

_reserved

See Also:

reserved

protected

ExpansionData *_reserved;

Discussion

Reserved for future use. (Internal use only)

IOPacketQueueDefaultCapacity

Describes the default capacity of the queue object.

protected

static const UInt32 IOPacketQueueDefaultCapacity = 100;

Discussion

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.

reserved

See Also:

_reserved

protected

ExpansionData *_reserved;

Discussion

Reserved for future use. (Internal use only)

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-12-19