Return to IOOQGateFIFOQueue.h CVS log

Up to [Apple XNU] / XNU / iokit / IOKit / network

Annotation of XNU/iokit/IOKit/network/IOOQGateFIFOQueue.h, revision 1.1

1.1     ! root        1: /*
        !             2:  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
        !             3:  *
        !             4:  * @APPLE_LICENSE_HEADER_START@
        !             5:  * 
        !             6:  * The contents of this file constitute Original Code as defined in and
        !             7:  * are subject to the Apple Public Source License Version 1.1 (the
        !             8:  * "License").  You may not use this file except in compliance with the
        !             9:  * License.  Please obtain a copy of the License at
        !            10:  * http://www.apple.com/publicsource and read it before using this file.
        !            11:  * 
        !            12:  * This Original Code and all software distributed under the License are
        !            13:  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
        !            14:  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
        !            15:  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
        !            16:  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
        !            17:  * License for the specific language governing rights and limitations
        !            18:  * under the License.
        !            19:  * 
        !            20:  * @APPLE_LICENSE_HEADER_END@
        !            21:  */
        !            22: /*
        !            23:  * Copyright (c) 1999 Apple Computer, Inc.  All rights reserved. 
        !            24:  *
        !            25:  * IOOQGateFIFOQueue.h
        !            26:  * 
        !            27:  * HISTORY
        !            28:  *
        !            29:  */
        !            30: 
        !            31: #ifndef _IOOQGATEFIFOQUEUE_H
        !            32: #define _IOOQGATEFIFOQUEUE_H
        !            33: 
        !            34: #include <IOKit/IOWorkLoop.h>
        !            35: #include <IOKit/IOCommandGate.h>
        !            36: #include <IOKit/network/IOOutputQueue.h>
        !            37: 
        !            38: /*! @class IOOQGateFIFOQueue
        !            39:         @abstract A concrete implementation of an IOOutputQueue. This object
        !            40:         provides a FIFO packet queue to hold the incoming packets provided
        !            41:         by the client transmit threads. An IOCommandGate in conjunction with
        !            42:         a workloop provided by the target is used to serialize access to the 
        !            43:         target's output handler, by always closing the gate in the IOCommandGate
        !            44:         before calling the target's output handler. Hence the target's handler
        !            45:         will run in a mutually exclusive fashion with any actions performed by
        !            46:         the workloop thread. See IOOutputQueue for additional information. */
        !            47: 
        !            48: class IOOQGateFIFOQueue : public IOOutputQueue
        !            49: {
        !            50:         OSDeclareDefaultStructors(IOOQGateFIFOQueue)
        !            51: 
        !            52: protected:
        !            53:         IOCommandGate *         _gate;
        !            54:         volatile bool           _serviceActive;
        !            55:         volatile UInt32         _enqueueCount;
        !            56: 
        !            57: /*! @function serviceThread
        !            58:         @discussion Provide an implementation for the interface defined in
        !            59:         IOOutputQueue. This method is called by a callout thread when
        !            60:         service() is performed asynchronously. */
        !            61: 
        !            62:         virtual void serviceThread();
        !            63: 
        !            64: /*! @function gatedDequeue
        !            65:         @discussion The naked dequeue() method not protected by the IOCommandGate.
        !            66:         dequeue() method will call gatedDequeue() with the command gate closed. */
        !            67: 
        !            68:         virtual void gatedDequeue();
        !            69:         
        !            70: /*! @function gatedStop
        !            71:         @discussion The naked stop() method not protected by the IOCommandGate.
        !            72:         stop() method will call gatedStop() with the command gate closed. */
        !            73: 
        !            74:         virtual void gatedStop();
        !            75: 
        !            76: /*! @function dequeue
        !            77:         @discussion Responsible for removing all packets from the queue and calling
        !            78:         the target's output handler. This method returns when the queue becomes
        !            79:         empty or if the queue's state is no longer kIOOQStateRunning. The target's
        !            80:         output handler is called for every packet removed from the queue. Only a
        !            81:         single packet is sent to the target for every call, the packets are never
        !            82:         chained. An IOCommandGate attached to an workloop provided by the target
        !            83:         ensures mutual exclusion between the dequeueing action (and calls to the
        !            84:         target's output handler), and any other action performed by the workloop's
        !            85:         thread.
        !            86:         */
        !            87: 
        !            88:         virtual void dequeue();
        !            89: 
        !            90: /*! @function free
        !            91:         @discussion Frees the IOOQGateFIFOQueue instance. */
        !            92: 
        !            93:         virtual void free();
        !            94: 
        !            95: public:
        !            96: 
        !            97: /*! @function init
        !            98:         @discussion Initialize an IOOQGateFIFOQueue instance.
        !            99:         @param target The object that shall receive packets from the queue,
        !           100:         and is usually a subclass of IONetworkController. If the target is
        !           101:         not an IONetworkController instance, then the target must immediately
        !           102:         call registerOutputHandler() after initializing the queue.
        !           103:         @param workloop A workloop object provided by the target that the
        !           104:         queue will use to add an internal IOCommandGate as an event source.
        !           105:         @param capacity The initial capacity of the output queue, defined as
        !           106:         the number of packets that the queue can hold without dropping.
        !           107:         @result true if initialized successfully, false otherwise. */
        !           108: 
        !           109:         virtual bool init(OSObject *   target,
        !           110:                               IOWorkLoop * workloop,
        !           111:                               UInt32       capacity = 0);
        !           112: 
        !           113: /*! @function withTarget
        !           114:         @discussion Factory method that will construct and initialize an
        !           115:         IOOQGateFIFOQueue instance.
        !           116:         @param target Same as init().
        !           117:         @param workloop Same as init().
        !           118:         @param capacity Same as init().
        !           119:         @result An IOOQGateFIFOQueue instance upon success, or 0 otherwise. */
        !           120: 
        !           121:         static IOOQGateFIFOQueue * withTarget(OSObject *   target,
        !           122:                                           IOWorkLoop * workloop,
        !           123:                                           UInt32       capacity = 0);
        !           124: 
        !           125: /*! @function enqueue
        !           126:         @discussion Handles packet (or a packet chain) sent to the queue.
        !           127:         This method can handle calls from multiple simultaneous client threads.
        !           128:         A client thread that calls enqueue() will call dequeue() with the
        !           129:         command gate closed if it detects that no other thread is actively
        !           130:         dequeueing packets from the queue. The dequeue() method will return
        !           131:         when the queue becomes empty, or if the target stalls the queue.
        !           132:         This method may block its caller.
        !           133:         @param The packet (or a packet chain) to be queued for transmission.
        !           134:         @result The number of dropped packets. */
        !           135: 
        !           136:         virtual UInt32 enqueue(struct mbuf * m);
        !           137: 
        !           138: /*! @function start
        !           139:         @discussion This method is called by the target to start the queue.
        !           140:         Once started, the queue will be allowed to call the target's
        !           141:         output handler. Before that, with the queue stopped, the queue will
        !           142:         absorb incoming packets sent to the enqueue() method, but no packets
        !           143:         will be dequeued, and the target's output handler will not be called.
        !           144:         @result true if the queue was successfully started, false otherwise. */
        !           145: 
        !           146:         virtual bool start();
        !           147: 
        !           148: /*! @function stop
        !           149:         @discussion Stops the queue to prevent it from calling the target's
        !           150:         output handler. This call is synchronous the caller may block.
        !           151:         The target's output handler must never call this method, or any other
        !           152:         queue methods. */
        !           153: 
        !           154:         virtual void stop();
        !           155: 
        !           156: /*! @function service
        !           157:         @discussion If the queue becomes stalled, then service() must be called
        !           158:         to restart the queue when the target is ready to accept more packets.
        !           159:         If the queue is not empty, this method will also call dequeue().
        !           160:         Note that if the target never sends a kIOOQReturnActionStall action 
        !           161:         code to the queue, then the queue will never stall on its own accord.
        !           162:         Calling this method on a running queue that is not stalled is harmless.
        !           163:         @param sync True if the service action should be performed synchronously,
        !           164:         false to perform the action asynchronously without blocking the caller,
        !           165:         but with a much higher latency cost.
        !           166:         @result true if the queue needed servicing, false otherwise. */
        !           167: 
        !           168:         virtual bool service(bool sync = true);
        !           169: };
        !           170: 
        !           171: #endif /* !_IOOQGATEFIFOQUEUE_H */

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.