Mac Developer Library

Developer

IOBasicOutputQueue Class Reference

Options
Deployment Target:

On This Page
Language:

IOBasicOutputQueue

A concrete implementation of an IOOutputQueue.

This object uses a mutex to protect the packet queue from multiple producers. A single producer is promoted to become a consumer when the queue is not active. Otherwise, the producer will simply queue the packet and return without blocking.

The flow of packets from the queue to its target can be controlled by calling methods such as start(), stop(), or service(). The target is expected to call those methods from a single threaded context, i.e. the work loop context in a network driver. In addition, the target must also return a status for every packet delivered by the consumer thread. This return value is the only mechanism that the target can use to manage the queue when it is running on the consumer thread.

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.
  • Adds a packet, or a chain of packets, to the queue.

    Declaration

    C++

    virtual UInt32 enqueue( mbuf_tm, void *param);

    Parameters

    m

    A single packet, or a chain of packets.

    param

    A parameter provided by the caller.

    Return Value

    Always returns 0.

    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. This method can be called by multiple client threads.

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

    Declaration

    C++

    virtual UInt32 flush();

    Return Value

    Returns the number of packets that were dropped and freed.

    Discussion

    To ensure that all packets are removed from the queue, stop() should be called prior to flush(), to make sure there are no packets in-flight and being delivered to the target.

  • Frees the IOBasicOutputQueue object.

    Declaration

    C++

    virtual void free();

    Discussion

    This function releases allocated resources, then call super::free().

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

    Declaration

    C++

    virtual UInt32 getCapacity() const;

    Return Value

    Returns the current queue capacity.

    Discussion

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

  • Gets the number of packets dropped by the queue.

    Declaration

    C++

    virtual UInt32 getDropCount();

    Return Value

    Returns the number of packets dropped due to over-capacity, or by external calls to the flush() method.

  • Gets the number of packets accepted by the target.

    Declaration

    C++

    virtual UInt32 getOutputCount();

    Return Value

    Returns the number of times that kIOOutputStatusAccepted is returned by the target.

  • Gets the number of instances when the target has refused to accept the packet provided.

    Declaration

    C++

    virtual UInt32 getRetryCount();

    Return Value

    Returns the number of times that kIOOutputStatusRetry is returned by the target.

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

    Declaration

    C++

    virtual UInt32 getSize() const;

    Return Value

    Returns the size of the queue.

  • Gets the number of instances when the target has stalled the queue.

    Declaration

    C++

    virtual UInt32 getStallCount();

    Return Value

    Returns the number of times that kIOOutputCommandStall is returned by the target.

  • Gets the state of the queue object.

    Declaration

    C++

    virtual UInt32 getState() const;

    Return Value

    Returns the current state of the queue object.

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

    Declaration

    C++

    virtual IONetworkData * getStatisticsData() const;

    Return Value

    Returns an IONetworkData object.

  • Handles an external access to the IONetworkData object returned by getStatisticsData().

    Declaration

    C++

    virtual IOReturn handleNetworkDataAccess( IONetworkData *data, UInt32type, void *param);

    Parameters

    data

    The IONetworkData object being accessed.

    type

    Description of the type of access being performed.

    param

    An optional parameter for the handler.

    Return Value

    Returns kIOReturnSuccess on success, or an error code otherwise.

  • Initializes an IOBasicOutputQueue object.

    Declaration

    C++

    virtual bool init( OSObject *target, IOOutputAction action, UInt32 capacity = 0, UInt32 priorities = 1);

    Parameters

    target

    The object that will handle packets removed from the queue, which is usually a subclass of IONetworkController.

    action

    The function that will handle packets removed from the queue.

    capacity

    The initial capacity of the output queue.

    Return Value

    Returns true if initialized successfully, false otherwise.

  • Transfers all packets in the mbuf queue to the target.

    Declaration

    C++

    virtual void output( IOMbufQueue *queue, UInt32 *state);

    Parameters

    queue

    A queue of output packets.

    state

    Returns a state bit defined by IOBasicOutputQueue that declares the new state of the queue following this method call. A kStateStalled is returned if the queue should stall, otherwise 0 is returned.

  • Services a queue that was stalled by the target.

    Declaration

    C++

    virtual bool service( IOOptionBits options = 0);

    Return Value

    Returns true if the queue was stalled and there were packets sitting in the queue awaiting delivery, false otherwise.

    Discussion

    A target that stalls the queue must call service() when it becomes ready to accept more packets. Calling this method when the queue is not stalled is harmless.

  • Provides an implementation for the serviceThread() method defined in IOOutputQueue.

    Declaration

    C++

    virtual void serviceThread( void *param);

    Parameters

    param

    A parameter that was given to scheduleServiceThread(). This parameter is not used.

    Discussion

    This method is called by the scheduled service thread when it starts to run. The service thread is scheduled by service() to restart a stalled queue when the kServiceAsync option is given.

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

    Declaration

    C++

    virtual bool setCapacity( UInt32capacity);

    Parameters

    capacity

    The new desired capacity.

    Return Value

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

  • Starts up the packet flow between the queue and its target.

    Declaration

    C++

    virtual bool start();

    Return Value

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

    Discussion

    Called by the target to start the queue. This will allow packets to be removed from the queue, and then delivered to the target.

  • Stops the packet flow between the queue and its target.

    Declaration

    C++

    virtual bool stop();

    Return Value

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

    Discussion

    This method stops the queue and prevents it from sending packets to its target. This call is synchronous and it may block. After this method returns, the queue will no longer call the registered target/action, even as new packets are added to the queue. The queue will continue to absorb new packets until the size of the queue reaches its capacity. The registered action must never call stop(), or a deadlock will occur.

  • Factory method that constructs and initializes an IOBasicOutputQueue object.

    Declaration

    C++

    static IOBasicOutputQueue * withTarget( IONetworkController *target, UInt32 capacity = 0);

    Parameters

    target

    An IONetworkController object that will handle packets removed from the queue.

    capacity

    The initial capacity of the output queue.

    Return Value

    Returns an IOBasicOutputQueue object on success, or 0 otherwise.

  • Factory method that constructs and initializes an IOBasicOutputQueue object.

    Declaration

    C++

    static IOBasicOutputQueue * withTarget( IONetworkController *target, UInt32capacity, UInt32priorities);

    Parameters

    target

    An IONetworkController object that will handle packets removed from the queue.

    capacity

    The initial capacity of the output queue.

    priorities

    The number of traffic priorities supported

    Return Value

    Returns an IOBasicOutputQueue object on success, or 0 otherwise.

  • Factory method that constructs and initializes an IOBasicOutputQueue object.

    Declaration

    C++

    static IOBasicOutputQueue * withTarget( OSObject *target, IOOutputAction action, UInt32 capacity = 0);

    Parameters

    target

    The object that will handle packets removed from the queue.

    action

    The function that will handle packets removed from the queue.

    capacity

    The initial capacity of the output queue.

    Return Value

    Returns an IOBasicOutputQueue object on success, or 0 otherwise.

  • Factory method that constructs and initializes an IOBasicOutputQueue object.

    Declaration

    C++

    static IOBasicOutputQueue * withTarget( OSObject *target, IOOutputActionaction, UInt32capacity, UInt32priorities);

    Parameters

    target

    The object that will handle packets removed from the queue.

    action

    The function that will handle packets removed from the queue.

    capacity

    The initial capacity of the output queue.

    priorities

    The number of traffic priorities supported

    Return Value

    Returns an IOBasicOutputQueue object on success, or 0 otherwise.

Constants

  • The bits in the value returned by getState().

    Declaration

    CPlusPlus

    enum { kStateRunning = 0x1, kStateOutputStalled = 0x2, kStateOutputActive = 0x4, kStateOutputServiceMask = 0xff00 };

    Constants

    • kStateRunning

      kStateRunning

      Set when the queue is running. Calling start() and stop() will set or clear this bit.

    • kStateStalled

      kStateStalled

      Set when the queue is stalled by the target.

    • kStateActive

      kStateActive

      Set when a consumer thread is actively removing packets from the queue and passing them to the target.

  • The option bits recognized by service().

    Declaration

    CPlusPlus

    enum { kServiceAsync = 0x1 };

    Constants

    • kServiceAsync

      kServiceAsync

      Set this option to service the queue in an asynchronous manner. The service() call will not block, but a scheduling latency will be introduced before the queue is serviced.