![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to IOOQGateFIFOQueue.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 IOOQGateFIFOQueue.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: * 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.