iokit/IOKit/network/IOPacketQueue.h

   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 declarations.
  39 //
  40 struct mbuf;
  41 struct IOMbufQueue;
  42
  43 // We do not want the enqueue/dequeue macros defined in queue.h.
  44 //
  45 // #warning queue.h should not be included
  46 #undef enqueue(queue,elt)
  47 #undef dequeue(queue)
  48
  49 /*! @class IOPacketQueue : public OSObject
  50     @abstract Implements a bounded FIFO queue of mbuf packets. Packets are
  51     removed from the head of the queue (dequeue), and new packets are added
  52     to the tail of the queue (enqueue). A spinlock is used to synchronize
  53     access to the queue between methods that have a "lock" prefix. */
  54
  55 class IOPacketQueue : public OSObject
  56 {
  57     OSDeclareDefaultStructors( IOPacketQueue )
  58
  59 protected:
  60     IOMbufQueue *   _queue;   // mbuf queue
  61     IOSimpleLock *  _lock;    // spinlock for synchronized methods
  62
  63     struct ExpansionData { };
  64     /*! @var reserved
  65         Reserved for future use.  (Internal use only)  */
  66     ExpansionData *_reserved;
  67
  68 /*! @function free
  69     @abstract Free the IOPacketQueue object.
  70     @discussion All packets held by the queue are released back to the free
  71     pool, resource are deallocated, then super::free() is called. */
  72
  73     virtual void free();
  74
  75 /*! @var IOPacketQueueDefaultCapacity Describes the default capacity of the
  76     queue object. The capacity is only observed by the enqueue() method.
  77     Therefore, it is possible for the size of the queue to exceed its
  78     capacity when other methods, such as prepend(), are used to add packets
  79     to the queue. */
  80
  81     static const UInt32 IOPacketQueueDefaultCapacity = 100;
  82
  83 public:
  84
  85 /*! @function withCapacity
  86     @abstract Factory method that will construct and initialize an
  87     IOPacketQueue object.
  88     @param capacity The initial capacity of the queue object. Can be
  89     later changed by calling the setCapacity() method.
  90     @result An IOPacketQueue instance on success, or 0 otherwise. */
  91
  92     static IOPacketQueue * withCapacity(UInt32 capacity =
  93                                         IOPacketQueueDefaultCapacity);
  94
  95 /*! @function initWithCapacity
  96     @abstract Initialize an IOPacketQueue object.
  97     @discussion Initialize an IOPacketQueue object with the given capacity.
  98     @param capacity The initial capacity of the queue. Can be later changed
  99     by calling the setCapacity() method.
 100     @result true if initialized successfully, false otherwise. */
 101
 102     virtual bool initWithCapacity(UInt32 capacity =
 103                                   IOPacketQueueDefaultCapacity);
 104
 105 /*! @function getSize
 106     @abstract Get the size of the queue.
 107     @result The number of packets currently held by the queue. */
 108
 109     virtual UInt32 getSize() const;
 110
 111 /*! @function setCapacity
 112     @abstract Change the capacity of the queue.
 113     @param capacity The new capacity.
 114     @result true if the new capacity was accepted, false otherwise. */
 115
 116     virtual bool setCapacity(UInt32 capacity);
 117
 118 /*! @function getCapacity
 119     @abstract Get the current capacity of the queue.
 120     @result The current queue capacity. */
 121
 122     virtual UInt32 getCapacity() const;
 123
 124 /*! @function peek
 125     @abstract Examine the packet at the head of the queue without
 126     removing it from the queue.
 127     @discussion A following call to peek() or dequeue() will return
 128     the same packet. The caller must never modify the mbuf packet returned.
 129     @result The packet at the head of the queue. */
 130
 131     virtual const struct mbuf * peek() const;
 132
 133 /*! @function prepend
 134     @abstract Add a chain of packets to the head of the queue.
 135     @param m A chain of packets to add to the head of the queue. */
 136
 137     virtual void prepend(struct mbuf * m);
 138
 139 /*! @function prepend
 140     @abstract Remove all packets from the specified queue, and add them
 141     to the head of this queue.
 142     @param queue The source IOPacketQueue object containing the packets to
 143     be transferred. */
 144
 145     virtual void prepend(IOPacketQueue * queue);
 146
 147 /*! @function lockPrepend
 148     @abstract Add a chain of packets to the head of a synchronized queue.
 149     @discussion A spinlock is used to synchronize access to the queue.
 150     @param m A chain of packets to add to the head of the queue.
 151     @result Will always return true. */
 152
 153     virtual void lockPrepend(struct mbuf * m);
 154
 155 /*! @function enqueue
 156     @abstract Add a chain of packets to the tail of the queue.
 157     @discussion Packets are not added if the size of the queue has reached
 158     its capacity.
 159     @param m A chain of packets to add to the tail of the queue.
 160     @result true on success, or false to indicate over-capacity and refusal
 161     to accept the packet chain provided. */
 162
 163     virtual bool enqueue(struct mbuf * m);
 164
 165 /*! @function enqueue
 166     @abstract Remove all packets from the specified queue, and add them
 167     to the tail of this queue.
 168     @param queue The source IOPacketQueue object containing the packets to
 169     be transferred.
 170     @result Always return true. */
 171
 172     virtual bool enqueue(IOPacketQueue * queue);
 173
 174 /*! @function enqueueWithDrop
 175     @abstract Add a chain of packets to the tail of the queue. Packets are
 176     dropped if the size of the queue has reached its capacity.
 177     @param m A chain of packets to add to the tail of the queue.
 178     @result The number of packets dropped and freed by the queue. */
 179
 180     virtual UInt32 enqueueWithDrop(struct mbuf * m);
 181
 182 /*! @function lockEnqueue
 183     @abstract Add a chain of packets to the tail of a synchronized queue.
 184     @discussion Packets are not added if the size of the queue has reached
 185     its capacity. A spinlock is used to synchronize access to the queue.
 186     @param m A chain of packets to add to the tail of the queue.
 187     @result true on success, or false to indicate over-capacity and refusal
 188     to accept the packet chain provided. */
 189
 190     virtual bool lockEnqueue(struct mbuf * m);
 191
 192 /*! @function lockEnqueueWithDrop
 193     @abstract Add a chain of packets to the tail of a synchronized queue.
 194     Packets are dropped if the size of the queue has reached its capacity.
 195     @discussion A spinlock is used to synchronize access to the queue.
 196     @param m A chain of packets to add to the tail of the queue.
 197     @result The number of packets dropped and freed by the queue. */
 198
 199     virtual UInt32 lockEnqueueWithDrop(struct mbuf * m);
 200
 201 /*! @function dequeue
 202     @abstract Remove a single packet from the head of the queue.
 203     @result A packet removed from the head of the queue, or NULL if the
 204     queue was empty. */
 205
 206     virtual struct mbuf * dequeue();
 207
 208 /*! @function lockDequeue
 209     @abstract Remove a single packet from the head of a synchronized queue.
 210     @discussion A spinlock is used to synchronize access to the queue.
 211     @result A packet removed from the head of the queue, or NULL if the
 212     queue was empty. */
 213
 214     virtual struct mbuf * lockDequeue();
 215
 216 /*! @function dequeueAll
 217     @abstract Remove all packets from the queue and return the head of the
 218     packet chain.
 219     @discussion The size of the queue is cleared to zero.
 220     @result The head of a packet chain linking all packets that were held
 221     in the queue, or NULL if the queue was empty. */
 222
 223     virtual struct mbuf * dequeueAll();
 224
 225 /*! @function lockDequeueAll
 226     @abstract Remove all packets from a synchronized queue and return the
 227     head of the packet chain.
 228     @discussion The size of the queue is cleared to zero. A spinlock is used
 229     to synchronize access to the queue.
 230     @result The head of a packet chain linking all packets that were held
 231     in the queue, or NULL if the queue was empty. */
 232
 233     virtual struct mbuf * lockDequeueAll();
 234
 235 /*! @function flush
 236     @abstract Free all packets currently held in the queue and release them
 237     back to the free mbuf pool.
 238     @discussion The size of the queue is cleared to zero.
 239     @result The number of packets freed. */
 240
 241     virtual UInt32 flush();
 242
 243 /*! @function lockFlush
 244     @abstract Free all packets currently held in a synchronized queue and
 245     release them back to the free mbuf pool.
 246     @discussion The size of the queue is cleared to zero. A spinlock is used
 247     to synchronize access to the queue.
 248     @result The number of packets freed. */
 249
 250     virtual UInt32 lockFlush();
 251
 252     // Virtual Pad functions
 253     OSMetaClassDeclareReservedUnused( IOPacketQueue,  0);
 254     OSMetaClassDeclareReservedUnused( IOPacketQueue,  1);
 255     OSMetaClassDeclareReservedUnused( IOPacketQueue,  2);
 256     OSMetaClassDeclareReservedUnused( IOPacketQueue,  3);
 257     OSMetaClassDeclareReservedUnused( IOPacketQueue,  4);
 258     OSMetaClassDeclareReservedUnused( IOPacketQueue,  5);
 259     OSMetaClassDeclareReservedUnused( IOPacketQueue,  6);
 260     OSMetaClassDeclareReservedUnused( IOPacketQueue,  7);
 261     OSMetaClassDeclareReservedUnused( IOPacketQueue,  8);
 262     OSMetaClassDeclareReservedUnused( IOPacketQueue,  9);
 263     OSMetaClassDeclareReservedUnused( IOPacketQueue, 10);
 264     OSMetaClassDeclareReservedUnused( IOPacketQueue, 11);
 265     OSMetaClassDeclareReservedUnused( IOPacketQueue, 12);
 266     OSMetaClassDeclareReservedUnused( IOPacketQueue, 13);
 267     OSMetaClassDeclareReservedUnused( IOPacketQueue, 14);
 268     OSMetaClassDeclareReservedUnused( IOPacketQueue, 15);
 269 };
 270
 271 #endif /* !_IOPACKETQUEUE_H */