![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to IOOQLockFIFOQueue.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / XNU / iokit / IOKit / network|
Return to IOOQLockFIFOQueue.h CVS log | Up to [Apple XNU] / XNU / iokit / IOKit / network |
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: * IOOQLockFIFOQueue.h
26: *
27: * HISTORY
28: *
29: */
30:
31: #ifndef _IOOQLOCKFIFOQUEUE_H
32: #define _IOOQLOCKFIFOQUEUE_H
33:
34: /*
35: * Aliases.
36: */
37: #define IOLockedFIFOQueue IOOQLockFIFOQueue
38:
39: #include <IOKit/IOLocks.h>
40: #include <IOKit/network/IOOutputQueue.h>
41:
42: /*! @class IOOQLockFIFOQueue
43: @abstract A concrete implementation of an IOOutputQueue. This object
44: provides a FIFO packet queue to hold the incoming packets provided
45: by the client transmit threads. A mutex lock is used to serialize
46: access to the target's output handler. The mutex lock is local to the
47: queue and there is no serialization performed between calls to the
48: target's output handler, and any other threads that may be running on
49: the target. See IOOutputQueue for additional information. */
50:
51: class IOOQLockFIFOQueue : public IOOutputQueue
52: {
53: OSDeclareDefaultStructors(IOOQLockFIFOQueue)
54:
55: protected:
56: IOLock * _mutex;
57: volatile bool _serviceActive;
58: volatile UInt32 _enqueueCount;
59:
60: /*! @function serviceThread
61: @discussion Provide an implementation for the interface defined in
62: IOOutputQueue. This method is called by a callout thread when
63: service() is performed asynchronously. */
64:
65: virtual void serviceThread();
66:
67: /*! @function dequeue
68: @discussion Responsible for removing all packets from the queue and calling
69: the target's output handler. This method returns when the queue becomes
70: empty or if the queue's state is no longer kIOOQStateRunning. The target's
71: output handler is called for every packet removed from the queue. Only a
72: single packet is sent to the target for every call, the packets are never
73: chained. A mutex lock enforces single threaded access to the target's
74: output handler. */
75:
76: virtual void dequeue();
77:
78: /*! @function free
79: @discussion Frees the IOOQLockFIFOQueue instance. */
80:
81: virtual void free();
82:
83: public:
84:
85: /*! @function init
86: @discussion Initialize an IOOQLockFIFOQueue instance.
87: @param target The object that shall receive packets from the queue,
88: and is usually a subclass of IONetworkController. If the target is
89: not an IONetworkController instance, then the target must immediately
90: call registerOutputHandler() after initializing the queue.
91: @param capacity The initial capacity of the output queue, defined as
92: the number of packets that the queue can hold without dropping.
93: @result true if initialized successfully, false otherwise. */
94:
95: virtual bool init(OSObject * target, UInt32 capacity = 0);
96:
97: /*! @function withTarget
98: @discussion Factory method that will construct and initialize an
99: IOOQLockFIFOQueue instance.
100: @param target Same as init().
101: @param capacity Same as init().
102: @result An IOOQLockFIFOQueue instance upon success, or 0 otherwise. */
103:
104: static IOOQLockFIFOQueue * withTarget(OSObject * target,
105: UInt32 capacity = 0);
106:
107: /*! @function enqueue
108: @discussion Handles packet (or a packet chain) sent to the queue.
109: This method can handle calls from multiple simultaneous client threads.
110: A client thread that calls enqueue() will acquire a mutex lock and
111: call dequeue() if it detects that no other thread is actively
112: dequeueing packets from the queue. The dequeue() method will return
113: when the queue becomes empty, or if the target stalls the queue.
114: This method may block its caller.
115: @param m The packet (or a packet chain) to be queued for transmission.
116: @result The number of dropped packets. */
117:
118: virtual UInt32 enqueue(struct mbuf * m);
119:
120: /*! @function start
121: @discussion This method is called by the target to start the queue.
122: Once started, the queue will be allowed to call the target's
123: output handler. Before that, with the queue stopped, the queue will
124: absorb incoming packets sent to the enqueue() method, but no packets
125: will be dequeued, and the target's output handler will not be called.
126: @result true if the queue was successfully started, false otherwise. */
127:
128: virtual bool start();
129:
130: /*! @function stop
131: @discussion Stops the queue to prevent it from calling the target's
132: output handler. This call is synchronous the caller may block.
133: The target's output handler must never call this method, or any other
134: queue methods. */
135:
136: virtual void stop();
137:
138: /*! @function service
139: @discussion If the queue becomes stalled, then service() must be called
140: to restart the queue when the target is ready to accept more packets.
141: If the queue is not empty, this method will also call dequeue().
142: Note that if the target never sends a kIOOQReturnActionStall action
143: code to the queue, then the queue will never stall on its own accord.
144: Calling this method on a running queue that is not stalled is harmless.
145: @param sync True if the service action should be performed synchronously,
146: false to perform the action asynchronously without blocking the caller,
147: but with a much higher latency cost.
148: @result true if the queue needed servicing, false otherwise. */
149:
150: virtual bool service(bool sync = true);
151: };
152:
153: #endif /* !_IOOQLOCKFIFOQUEUE_H */
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.