Return to IOPacketQueue.h CVS log

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

Annotation of XNU/iokit/IOKit/network/IOPacketQueue.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) 1998 Apple Computer, Inc.  All rights reserved. 
        !            24:  *
        !            25:  * IOPacketQueue.h
        !            26:  *
        !            27:  * HISTORY
        !            28:  * 9-Dec-1998       Joe Liu (jliu) created.
        !            29:  *
        !            30:  */
        !            31: 
        !            32: #ifndef _IOPACKETQUEUE_H
        !            33: #define _IOPACKETQUEUE_H
        !            34: 
        !            35: #include <libkern/c++/OSObject.h>
        !            36: #include <IOKit/IOLocks.h>
        !            37: 
        !            38: // Forward structure declarations.
        !            39: //
        !            40: struct mbuf;
        !            41: 
        !            42: // We do not want the enqueue/dequeue macros defined in queue.h.
        !            43: //
        !            44: // #warning queue.h should not be included
        !            45: #undef enqueue(queue,elt)
        !            46: #undef dequeue(queue)
        !            47: 
        !            48: /*! @class IOPacketQueue
        !            49:     @abstract Implements a FIFO queue of mbuf packets.
        !            50:     A spinlock allocated by this object is used to enforce mutual
        !            51:     exclusion between methods with a "lock" prefix. */
        !            52: 
        !            53: class IOPacketQueue : public OSObject
        !            54: {   
        !            55:     OSDeclareDefaultStructors(IOPacketQueue)
        !            56: 
        !            57: private:
        !            58:     struct mbuf *   _head;          // head of the mbuf queue
        !            59:     struct mbuf *   _tail;          // tail of the mbuf queue
        !            60:     UInt32          _size;          // size of the queue
        !            61:     UInt32          _peakSize;      // peak size of the queue
        !            62:     UInt32          _capacity;      // maximum size of the queue
        !            63:     IOSimpleLock *  _lock;          // spinlock for locking methods
        !            64: 
        !            65: /*! @function free
        !            66:     @abstract Free the IOPacketQueue instance.
        !            67:     @discussion Release all packets in the queue to the free mbuf pool,
        !            68:     deallocate the spinlock, then call super::free(). */
        !            69: 
        !            70:     virtual void free();
        !            71: 
        !            72: /*! @var IOPQDefaultCapacity Specifies the default capacity of the queue
        !            73:     (number of packets that the queue can hold). Once the size of the queue
        !            74:     grows to its capacity, the queue will begin to drop incoming packets.
        !            75:     This capacity can be overridden by specifying the desired capacity when
        !            76:     the queue is initialized, or the setCapacity() method can be called to 
        !            77:     adjust the queue's capacity. */
        !            78: 
        !            79:     static const UInt32 IOPQDefaultCapacity = 100;
        !            80: 
        !            81: public:
        !            82: 
        !            83: /*! @function freePacketChain
        !            84:     @abstract Free a packet chain.
        !            85:     @discussion Traverse a packet chain linked through the mbuf
        !            86:     nextpkt field, and free each packet.
        !            87:     @param m The mbuf at the head of the mbuf chain.
        !            88:     @result The number of mbufs freed. */
        !            89: 
        !            90:     static UInt32 freePacketChain(struct mbuf * m);
        !            91: 
        !            92: /*! @function withCapacity
        !            93:     @abstract Factory method that will construct and initialize an
        !            94:     IOPacketQueue instance.
        !            95:     @param capacity The initial capacity of the queue. Can be changed
        !            96:     later through setCapacity().
        !            97:     @result An IOPacketQueue instance on success, or 0 otherwise. */
        !            98: 
        !            99:     static IOPacketQueue * withCapacity(UInt32 capacity = IOPQDefaultCapacity);
        !           100: 
        !           101: /*! @function initWithCapacity
        !           102:     @abstract Initialize an IOPacketQueue instance.
        !           103:     @discussion Initialize the queue and create a spinlock.
        !           104:     @param capacity The initial capacity of the queue. Can be changed
        !           105:     later through setCapacity().
        !           106:     @result true if initialized successfully, false otherwise. */
        !           107: 
        !           108:     virtual bool initWithCapacity(UInt32 capacity = IOPQDefaultCapacity);
        !           109: 
        !           110: /*! @function getSize
        !           111:     @abstract Get the size of the queue.
        !           112:     @result The number of packets currently held in the queue. */
        !           113: 
        !           114:     UInt32 getSize() const;
        !           115: 
        !           116: /*! @function getPeakSize
        !           117:     @abstract Returns the peak size of the queue.
        !           118:     @discussion The queue contains a counter that records the peak
        !           119:     size of the queue. This method returns the value in the counter,
        !           120:     and can optionally reset the counter back to zero.
        !           121:     @param reset Reset the peak size counter to zero if true.
        !           122:     @result The peak size count. */
        !           123: 
        !           124:     UInt32 getPeakSize(bool reset = false);
        !           125: 
        !           126: /*! @function setCapacity
        !           127:     @abstract Adjust the queue's capacity.
        !           128:     @discussion If the capacity is set to a value that is smaller than its 
        !           129:     current size, then the queue will drop incoming packets, but existing 
        !           130:     packets in the queue will remain intact.
        !           131:     @param capacity The new capacity.
        !           132:     @result true if the new capacity was accepted, false otherwise. */
        !           133: 
        !           134:     bool setCapacity(UInt32 capacity);
        !           135: 
        !           136: /*! @function getCapacity
        !           137:     @abstract Get the capacity of the queue.
        !           138:     @result The current queue capacity. */
        !           139: 
        !           140:     UInt32 getCapacity() const;
        !           141: 
        !           142: /*! @function peek
        !           143:     @discussion Peek at the head of the queue without dequeueing the packet.
        !           144:     An ensuing call to peek() or dequeue() will return the same packet.
        !           145:     The caller must not modify the packet returned.
        !           146:     @result The packet at the head of the queue. */
        !           147: 
        !           148:     const struct mbuf * peek() const;
        !           149: 
        !           150: /*! @function prepend
        !           151:     @abstract Add a packet (or a packet chain) to the head of the queue.
        !           152:     @discussion Unlike enqueue(), the capacity is not checked, and the input
        !           153:     packet is never dropped.
        !           154:     @param m A single packet, or packet chain, to be added to the head of the
        !           155:     queue. */
        !           156: 
        !           157:     void prepend(struct mbuf * m);
        !           158: 
        !           159: /*! @function lockPrepend
        !           160:     @abstract Add a packet (or a packet chain) to the head of the queue.
        !           161:     @discussion Same as prepend(). A spinlock lock is held while the queue
        !           162:     is modified.
        !           163:     @param m A single packet, or packet chain, to be added to the head of the
        !           164:     queue. */
        !           165: 
        !           166:     void lockPrepend(struct mbuf * m);
        !           167: 
        !           168: /*! @function enqueue
        !           169:     @abstract Add a packet (or a packet chain) to the tail of the queue.
        !           170:     @param m A single packet, or a packet chain, to be added to the tail of the
        !           171:     queue.
        !           172:     @result The number of packets dropped from over-capacity. */
        !           173: 
        !           174:     UInt32 enqueue(struct mbuf * m);
        !           175: 
        !           176: /*! @function lockEnqueue
        !           177:     @abstract Add a packet (or a packet chain) to the tail of the queue.
        !           178:     @discussion Same as enqueue(). A spinlock lock is held while the queue
        !           179:     is modified.
        !           180:     @param m A single packet, or a packet chain, to be added to the tail of the
        !           181:     queue.
        !           182:     @result The number of packets dropped from over-capacity. */
        !           183: 
        !           184:     UInt32 lockEnqueue(struct mbuf * m);
        !           185: 
        !           186: /*! @function dequeue
        !           187:     @abstract Remove a single packet from the head of the queue.
        !           188:     @result The dequeued packet. A NULL is returned if the queue is empty. */
        !           189: 
        !           190:     struct mbuf * dequeue();
        !           191: 
        !           192: /*! @function lockDequeue
        !           193:     @abstract Remove a single packet from the head of the queue.
        !           194:     @discussion Same as dequeue(). A spinlock lock is held while the queue
        !           195:     is modified.
        !           196:     @result The dequeued packet. A NULL is returned if the queue is empty. */
        !           197: 
        !           198:     struct mbuf * lockDequeue();
        !           199: 
        !           200: /*! @function dequeueAll
        !           201:     @abstract Removes all packets from the queue and return the first packet
        !           202:     of the packet chain.
        !           203:     @result The head of the dequeued packet chain. */
        !           204: 
        !           205:     struct mbuf * dequeueAll();
        !           206: 
        !           207: /*! @function lockDequeueAll
        !           208:     @abstract Removes all packets from the queue and return the first packet
        !           209:     of the packet chain.
        !           210:     @discussion Same as dequeueAll(). A spinlock lock is held while the queue
        !           211:     is modified.
        !           212:     @result The head of the dequeued packet chain. */
        !           213: 
        !           214:     struct mbuf * lockDequeueAll();
        !           215: 
        !           216: /*! @function flush
        !           217:     @abstract Removes all packets from the queue and release them to the
        !           218:     free mbuf pool.
        !           219:     @discussion The size of the queue will be zero after the call.
        !           220:     @result The number of packets freed. */
        !           221: 
        !           222:     UInt32 flush();
        !           223: 
        !           224: /*! @function lockFlush
        !           225:     @abstract Removes all packets from the queue and release them to the
        !           226:     free mbuf pool.
        !           227:     @discussion Same as flush(). A spinlock lock is held while the queue
        !           228:     is modified.
        !           229:     @result The number of packets freed. */
        !           230: 
        !           231:     UInt32 lockFlush();
        !           232: };
        !           233: 
        !           234: #endif /* !_IOPACKETQUEUE_H */

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