Mac Developer Library

Developer

IOOutputQueue Class Reference

Options
Deployment Target:

On This Page
Language:

IOOutputQueue

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.

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.

  • Cancels any pending service thread callout.

    Declaration

    C++

    virtual bool cancelServiceThread();

    Return Value

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

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

    Declaration

    C++

    virtual UInt32 enqueue( mbuf_tm, 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.

  • Drops and frees all packets currently held by the queue.

    Declaration

    C++

    virtual UInt32 flush() = 0;

    Return Value

    Returns the number of packets that were dropped and freed.

  • Frees the IOOutputQueue object.

    Declaration

    C++

    virtual void free();

    Discussion

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

  • Gets the number of packets that the queue can hold.

    Declaration

    C++

    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.

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

    Declaration

    C++

    virtual UInt32 getMbufPriority( mbuf_tm);

    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.

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

    Declaration

    C++

    virtual IOOutputAction getOutputHandler() const;

    Return Value

    Returns the address of the enqueue() method.

  • Gets the number of packets currently held in the queue.

    Declaration

    C++

    virtual UInt32 getSize() const = 0;

    Return Value

    Returns the size of the queue.

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

    Declaration

    C++

    virtual IONetworkData * getStatisticsData() const;

    Return Value

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

  • Initializes an IOOutputQueue object.

    Declaration

    C++

    virtual bool init();

    Return Value

    Returns true if initialized successfully, false otherwise.

  • Schedules a service thread callout.

    Declaration

    C++

    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.

  • Services the queue.

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    virtual bool setCapacity( UInt32capacity) = 0;

    Parameters

    capacity

    The new desired capacity.

    Return Value

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

  • Starts up the queue.

    Declaration

    C++

    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.

  • Stops the queue.

    Declaration

    C++

    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 for future use. (Internal use only)

    Declaration

    C++

    ExpansionData *_reserved;

  • Reserved for future use. (Internal use only)

    Declaration

    C++

    ExpansionData *_reserved;