IOOQGateFIFOQueue



Member Functions

dequeue

protected:

virtual void dequeue();

Responsible for removing all packets from the queue and calling the target's output handler. This method returns when the queue becomes empty or if the queue's state is no longer kIOOQStateRunning. The target's output handler is called for every packet removed from the queue. Only a single packet is sent to the target for every call, the packets are never chained. An IOCommandGate attached to an workloop provided by the target ensures mutual exclusion between the dequeueing action (and calls to the target's output handler), and any other action performed by the workloop's thread.


enqueue

public:

virtual UInt32 enqueue(struct mbuf * m);

Handles packet (or a packet chain) sent to the queue. This method can handle calls from multiple simultaneous client threads. A client thread that calls enqueue() will call dequeue() with the command gate closed if it detects that no other thread is actively dequeueing packets from the queue. The dequeue() method will return when the queue becomes empty, or if the target stalls the queue. This method may block its caller.

Parameters

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

free

protected:

virtual void free();

Frees the IOOQGateFIFOQueue instance.


gatedDequeue

protected:

virtual void gatedDequeue();

The naked dequeue() method not protected by the IOCommandGate. dequeue() method will call gatedDequeue() with the command gate closed.


gatedStop

protected:

virtual void gatedStop();

The naked stop() method not protected by the IOCommandGate. stop() method will call gatedStop() with the command gate closed.


init

public:

virtual bool init(OSObject * target, IOWorkLoop * workloop, UInt32 capacity = 0);

Initialize an IOOQGateFIFOQueue 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.
workloopA workloop object provided by the target that the queue will use to add an internal IOCommandGate as an event source.
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.

service

public:

virtual bool service(bool sync = true);

If the queue becomes stalled, then service() must be called to restart the queue when the target is ready to accept more packets. If the queue is not empty, this method will also call dequeue(). 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();

Provide an implementation for the interface defined in IOOutputQueue. This method is called by a callout thread when service() is performed asynchronously.


start

public:

virtual bool start();

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();

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.


withTarget

public:

static IOOQGateFIFOQueue * withTarget(OSObject * target, IOWorkLoop * workloop, UInt32 capacity = 0);

Factory method that will construct and initialize an IOOQGateFIFOQueue instance.

Parameters

NameDescription
targetSame as init().
workloopSame as init().
capacitySame as init().
Result: An IOOQGateFIFOQueue instance upon success, or 0 otherwise.

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