IOOutputQueue

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

Overview

A packet queue that supports multiple producers and a single consumer.

Each producer, or a client thread, will deliver a chain of packets to the queue. A single consumer will remove packets from the queue one at a time and forward it to the registered target/action. This object may be used by an IONetworkController on the output (transmit) side to handle the output packet flow downstream from an IONetworkInterface, and then call the driver's output function. IOOutputQueue is an abstract class that provides an interface for its subclasses. Concrete subclasses will complete the implementation, and specify the context that the target is called for packets removed from the queue.

Tasks

Miscellaneous

Instance Methods

cancelServiceThread

Cancels any pending service thread callout.

virtual bool cancelServiceThread();
Return Value

Returns true if a previously scheduled thread callout was canceled, false otherwise.

enqueue

Adds a packet, or a chain of packets, to the queue.

virtual UInt32 enqueue( mbuf_t m, void *param) = 0;
Parameters
m

A single packet, or a chain of packets.

param

A parameter provided by the caller.

Return Value

Returns a return code.

Discussion

This method is called by a client to add a packet, or a chain of packets, to the queue. A packet is described by an mbuf chain, while a chain of packets is constructed by linking multiple mbuf chains via the m_nextpkt field.

flush

Drops and frees all packets currently held by the queue.

virtual UInt32 flush() = 0;
Return Value

Returns the number of packets that were dropped and freed.

free

Frees the IOOutputQueue object.

virtual void free();
Discussion

Release allocated resources, then call super::free().

getCapacity

Gets the number of packets that the queue can hold.

virtual UInt32 getCapacity() const = 0;
Return Value

Returns the current queue capacity.

Discussion

The queue will begin to drop incoming packets when the size of queue reaches its capacity.

getMbufPriority

Determines an mbuf's traffic priority. The highest priority is 0.

virtual UInt32 getMbufPriority( mbuf_t m);
Parameters
m

An mbuf to analyze.

Return Value

Returns a UInt32 representing the priority of the packet. 0 is the highest priority.

Discussion

A queue can prioritize certain classes of traffic. This method facilitates that by evaluating an mbuf and returning its priority.

getOutputHandler

Returns the address of a function that is designated to handle incoming packets sent to the queue object.

virtual IOOutputAction getOutputHandler() const;
Return Value

Returns the address of the enqueue() method.

getSize

Gets the number of packets currently held in the queue.

virtual UInt32 getSize() const = 0;
Return Value

Returns the size of the queue.

getStatisticsData

Returns an IONetworkData object containing statistics counters updated by the queue.

virtual IONetworkData * getStatisticsData() const;
Return Value

Returns an IONetworkData object. This implementation will always return 0.

init

Initializes an IOOutputQueue object.

virtual bool init();
Return Value

Returns true if initialized successfully, false otherwise.

scheduleServiceThread

Schedules a service thread callout.

virtual bool scheduleServiceThread( void *param = 0);
Parameters
param

A parameter to pass to the serviceThread() method.

Return Value

Returns true if a thread callout was scheduled, false otherwise.

Discussion

This method can be called by service() to schedule a thread that will call serviceThread() when it starts running.

service

Services the queue.

virtual bool service( IOOptionBits options = 0) = 0;
Parameters
options

Options for the service request.

Return Value

Returns a return value to indicate the service result.

Discussion

Manage the queue after it has been started.

serviceThread

Method called by the scheduled service thread when it starts to run.

virtual void serviceThread( void *param);
Parameters
param

A parameter that was given to scheduleServiceThread() when the service thread was scheduled.

Discussion

Must be implemented by a subclass that calls scheduleServiceThread(). The default implementation does nothing.

setCapacity

Changes the number of packets that the queue can hold before it begins to drop excess packets.

virtual bool setCapacity( UInt32 capacity) = 0;
Parameters
capacity

The new desired capacity.

Return Value

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

start

Starts up the queue.

virtual bool start() = 0;
Return Value

Returns true if the queue was started successfully, false otherwise.

Discussion

This method is called by the target to start the queue. This will allow packets to be removed from the queue, then delivered to the target.

stop

Stops the queue.

virtual bool stop() = 0;
Return Value

Returns the previous running state of the queue, true if the queue was running, false if the queue was already stopped.

Discussion

Stop the queue and prevent it from sending packets to its target.

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