IOOutputQueue



Member Functions

cancelServiceThread

protected:

virtual bool cancelServiceThread();

Cancel the service thread callout. Subclasses should not override this method.

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

createPacketQueue

protected:

virtual IOPacketQueue * createPacketQueue(UInt32 capacity) const;

Allows subclasses to override the default action, which is to allocate and return an IOPacketQueue instance. The returned object is used to implement the queueing behavior of the IOOutputQueue.

Parameters

NameDescription
capacityThe initial capacity of the queue.
Result: A newly allocated and initialized IOPacketQueue instance.

enqueue

public:

virtual UInt32 enqueue(struct mbuf * m) = 0;

Handles packet (or a packet chain) sent to the queue. This method can handle calls from multiple simultaneous client threads. A pointer to this function is written to the "output" field in the IOOutputHandler structure by getOutputHandler(), thus allowing client objects to call this method in order to process the output packet.

Parameters

NameDescription
mThe packet (or a packet chain) to be queued for transmission.
Result: The number of dropped packets.

flush

public:

virtual UInt32 flush();

Release all packets held in the queue. The size of the queue is reset to zero. The drop packet counter is incremented by the number of packets freed. See getDropCount().

Result: The number of packets freed.

free

protected:

virtual void free();

Frees the IOOutputQueue instance.


getCapacity

public:

virtual UInt32 getCapacity() const;

Result: The current queue capacity.

getDropCount

public:

virtual UInt32 getDropCount(bool reset = false);

This method returns the number of times that a kIOOQReturnStatusDropped status code is received from the target's output handler, indicating that the packet given was dropped. This count is also incremented when the queue drops a packet due to overcapacity, or by an explicit flush() call.

Parameters

NameDescription
resetResets the counter if true.
Result: The number of dropped packets.

getOutputCount

public:

virtual UInt32 getOutputCount(bool reset = false);

This method returns the number of times that a kIOOQReturnStatusSuccess status code is received from the target's output handler, indicating that the packet given was accepted, and is ready to be (or already has been) transmitted.

Parameters

NameDescription
resetResets the counter if true.
Result: The number of packets accepted by our target.

getOutputHandler

public:

void getOutputHandler(IOOutputHandler * handler) const;

This method will write to the fields in the IOOutputHandler structure allocated by the caller. This method is called to discover the methods implemented by this object used to handle outbound packets and requests.

Parameters

NameDescription
handlerPointer to an IOOutputHandler structure passed in by the caller.

getPeakSize

public:

virtual UInt32 getPeakSize(bool reset = false);

Parameters

NameDescription
resetResets the counter if true.
Result: The peak queue size.

getRetryCount

public:

virtual UInt32 getRetryCount(bool reset = false);

This method returns the number of times that a kIOOQReturnStatusRetry status code is received from the target's output handler, indicating that the target is temporarily unable to handle the packet given, and the queue should try to resend the same packet at some later time.

Parameters

NameDescription
resetResets the counter if true.
Result: The number of retries issued by the target.

getSize

public:

virtual UInt32 getSize() const;

Result: The current queue size.

getStallCount

public:

virtual UInt32 getStallCount(bool reset = false);

Each time the queue is stalled, when a kIOOQReturnActionStall action code is received from the target's output handler, a counter is incremented. This method returns the value stored in this counter.

Parameters

NameDescription
resetResets the counter if true.
Result: The number of times that the queue was stalled.

getState

public:

virtual IOOQState getState() const;

Result: The current state of the queue object. See IOOQState enumeration.

init

protected:

virtual bool init(OSObject * target, UInt32 capacity);

Initialize an IOOutputQueue instance.

Parameters

NameDescription
targetThe object that shall receive packets from the queue, and is usually a subclass of IONetworkController. If the target is not an IONetworkController instance, then the target must immediately call registerOutputHandler() after initializing the queue.
capacityThe initial capacity of the output queue, defined as the number of packets that the queue can hold without dropping.
Result: true if initialized successfully, false otherwise.

publishParameters

protected:

virtual void publishParameters(OSDictionary * paramDict);

Called by an interface object to collect IONetworkParameter objects. IOOutputQueue will add a parameter, containing an IOOutputQueueStats structure, to the dictionary provided. This dictionary and the objects (and data) contained within can be serialized to user-space, allowing the queue statistics to be visible outside of the kernel.

Parameters

NameDescription
Adictionary provided by the interface object that is used as a parameter container.

registerOutputHandler

public:

bool registerOutputHandler(const IOOutputHandler * handler);

Register the target object, and methods to call needed for the queue to send packets and requests downstream. The caller must provide a pointer to an IOOutputHandler structure that has been initialized.

Parameters

NameDescription
handlerPointer to an initialized IOOutputHandler structure passed in by the caller.
Result: true if the structure given was accepted, otherwise return false.

requestHandler

public:

IOReturn requestHandler(OSObject * sender, UInt32 request, void * arg0 = 0, void * arg1 = 0, void * arg2 = 0, void * arg3 = 0);

Handle a request sent from the interface object.

Parameters

NameDescription
senderThe sender of the request.
requestThe request type. The types handled by this class are kRequestSetOutputQueueCapacity, kRequestGetOutputQueueCapacity, kRequestGetOutputQueueSize, kRequestFlushOutputQueue, and kRequestPublishParameters.
arg0Request argument.
arg1Request argument.
arg2Request argument.
arg3Request argument.
Result: kIOReturnSuccess if the request was successfully handled, otherwise an appropriate error code is returned.

runServiceThread

protected:

static void runServiceThread(IOOutputQueue * self, thread_call_param_t);

A glue function that is registered as the service thread callout handler. This function in turn will call the serviceThread() method.

Parameters

NameDescription
selfAn argument previously registered with the callout to identify the IOOutputQueue instance associated with the callout.

scheduleServiceThread

protected:

virtual bool scheduleServiceThread();

Schedule a service thread callout, which will then execute the serviceThread() method. Subclasses should not override this method.

Result: true if scheduling the thread callout was successful, false otherwise.

service

public:

virtual bool service(bool sync = true) = 0;

If the queue becomes stalled, then service() must be called to restart the queue when the target is ready to accept more packets. Note that if the target never sends a kIOOQReturnActionStall action code to the queue, then the queue will never stall on its own accord. Calling this method on a running queue that is not stalled is harmless.

Parameters

NameDescription
syncTrue if the service action should be performed synchronously, false to perform the action asynchronously without blocking the caller, but with a much higher latency cost.
Result: true if the queue needed servicing, false otherwise.

serviceThread

protected:

virtual void serviceThread();

Must be implemented by subclasses that calls scheduleServiceThread(). The default implementation is a placeholder and performs no useful action.


setCapacity

public:

virtual bool setCapacity(UInt32 capacity);

Parameters

NameDescription
capacityThe new capacity of the queue.
Result: true if the new capacity was accepted, false otherwise.

start

public:

virtual bool start() = 0;

This method is called by the target to start the queue. Once started, the queue will be allowed to call the target's output handler. Before that, with the queue stopped, the queue will absorb incoming packets sent to the enqueue() method, but no packets will be dequeued, and the target's output handler will not be called.

Result: true if the queue was successfully started, false otherwise.

stop

public:

virtual void stop() = 0;

Stops the queue to prevent it from calling the target's output handler. This call is synchronous the caller may block. The target's output handler must never call this method, or any other queue methods.


© 2000 Apple Computer, Inc. — (Last Updated 2/23/2000)