Root/
Source at commit 1085 created 13 years 1 month ago. By azimutz, Runaway "min"; fixes build. | |
---|---|
1 | /*␊ |
2 | * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.␊ |
3 | *␊ |
4 | * @APPLE_OSREFERENCE_LICENSE_HEADER_START@␊ |
5 | * ␊ |
6 | * This file contains Original Code and/or Modifications of Original Code␊ |
7 | * as defined in and that are subject to the Apple Public Source License␊ |
8 | * Version 2.0 (the 'License'). You may not use this file except in␊ |
9 | * compliance with the License. The rights granted to you under the License␊ |
10 | * may not be used to create, or enable the creation or redistribution of,␊ |
11 | * unlawful or unlicensed copies of an Apple operating system, or to␊ |
12 | * circumvent, violate, or enable the circumvention or violation of, any␊ |
13 | * terms of an Apple operating system software license agreement.␊ |
14 | * ␊ |
15 | * Please obtain a copy of the License at␊ |
16 | * http://www.opensource.apple.com/apsl/ and read it before using this file.␊ |
17 | * ␊ |
18 | * The Original Code and all software distributed under the License are␊ |
19 | * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER␊ |
20 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,␊ |
21 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,␊ |
22 | * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.␊ |
23 | * Please see the License for the specific language governing rights and␊ |
24 | * limitations under the License.␊ |
25 | * ␊ |
26 | * @APPLE_OSREFERENCE_LICENSE_HEADER_END@␊ |
27 | */␊ |
28 | ␊ |
29 | /*␊ |
30 | *␊ |
31 | *␉Copyright (c) 2000 Apple Computer, Inc. All rights reserved.␊ |
32 | *␊ |
33 | *␉HISTORY␊ |
34 | *␊ |
35 | *␉2001-01-17␉gvdl␉Re-implement on IOCommandGate::commandSleep␊ |
36 | *␉11/13/2000␉CJS␉Created IOCommandPool class and implementation␊ |
37 | *␊ |
38 | */␊ |
39 | ␊ |
40 | /*!␊ |
41 | * @header IOCommandPool␊ |
42 | * @abstract␊ |
43 | * This header contains the IOCommandPool class definition.␊ |
44 | */␊ |
45 | ␊ |
46 | #ifndef _IOKIT_IO_COMMAND_POOL_H_␊ |
47 | #define _IOKIT_IO_COMMAND_POOL_H_␊ |
48 | ␊ |
49 | /*␊ |
50 | * Kernel␊ |
51 | */␊ |
52 | ␊ |
53 | #if defined(KERNEL) && defined(__cplusplus)␊ |
54 | ␊ |
55 | #include <kern/kern_types.h>␊ |
56 | #include <kern/queue.h>␊ |
57 | #include <IOKit/IOCommand.h>␊ |
58 | #include <IOKit/IOCommandGate.h>␊ |
59 | #include <IOKit/IOService.h>␊ |
60 | #include <IOKit/IOWorkLoop.h>␊ |
61 | ␊ |
62 | /*!␊ |
63 | * @class IOCommandPool␊ |
64 | * @abstract Manipulates a pool of commands which inherit from IOCommand.␊ |
65 | * @discussion␊ |
66 | * The IOCommandPool class is used to manipulate a pool of commands which␊ |
67 | * inherit from IOCommand. It includes a factory method to create a pool␊ |
68 | * of a certain size. Once the factory method is invoked, the semaphore␊ |
69 | * is set to zero. The caller must then put commands in the pool by creating␊ |
70 | * the command (via the controller's factory method or a memory allocation)␊ |
71 | * and calling the returnCommand method with the newly created command as its␊ |
72 | * argument.␊ |
73 | */␊ |
74 | ␊ |
75 | class IOCommandPool : public OSObject␊ |
76 | {␊ |
77 | ␉␊ |
78 | OSDeclareDefaultStructors(IOCommandPool)␊ |
79 | ␊ |
80 | ␊ |
81 | protected:␊ |
82 | ␊ |
83 | queue_head_t fQueueHead;␉/* head of the queue of elements available */␊ |
84 | UInt32 fSleepers;␉␉/* Count of threads sleeping on this pool */␊ |
85 | IOCommandGate *fSerializer;␉/* command gate used for serializing pool access */␊ |
86 | ␊ |
87 | /*! @struct ExpansionData␊ |
88 | @discussion This structure will be used to expand the capablilties of the IOEventSource in the future.␊ |
89 | */ ␊ |
90 | struct ExpansionData { };␊ |
91 | ␊ |
92 | /*! @var reserved␊ |
93 | Reserved for future use. (Internal use only) */␊ |
94 | ExpansionData *reserved;␊ |
95 | ␊ |
96 | /*!␊ |
97 | * @const kIOCommandPoolDefaultSize␊ |
98 | * @abstract The default size of any command pool.␊ |
99 | * @discussion␊ |
100 | * kIOCommandPoolDefaultSize is the default size of any command pool.␊ |
101 | * The default size was determined to be the smallest size for which␊ |
102 | * a pool makes sense.␊ |
103 | */␊ |
104 | ␊ |
105 | static const UInt32 kIOCommandPoolDefaultSize = 2;␊ |
106 | ␊ |
107 | /*␊ |
108 | * Free all of this object's outstanding resources.␊ |
109 | */␊ |
110 | ␊ |
111 | virtual void free(void);␊ |
112 | ␊ |
113 | ␊ |
114 | public:␊ |
115 | ␊ |
116 | /*!␊ |
117 | * @function initWithWorkLoop␊ |
118 | * @abstract Primary initializer for an IOCommandPool object.␊ |
119 | * @discussion Primary initializer for an IOCommandPool.␊ |
120 | * Should probably use IOCommandPool::withWorkLoop() as it is easier to use.␊ |
121 | * @param inWorkLoop␊ |
122 | * The workloop that this command pool should synchronize with.␊ |
123 | * @result Returns true if command pool was successfully initialized.␊ |
124 | */␊ |
125 | virtual bool initWithWorkLoop(IOWorkLoop *workLoop);␊ |
126 | ␊ |
127 | /*!␊ |
128 | * @function withWorkLoop␊ |
129 | * @abstract Primary factory method for the IOCommandPool class␊ |
130 | * @discussion␊ |
131 | * The withWorkLoop method is what is known as a factory method. It creates␊ |
132 | * a new instance of an IOCommandPool and returns a pointer to that object.␊ |
133 | * @param inWorkLoop␊ |
134 | * The workloop that this command pool should synchronize with.␊ |
135 | * @result␊ |
136 | * Returns a pointer to an instance of IOCommandPool if successful,␊ |
137 | * otherwise NULL.␊ |
138 | */␊ |
139 | ␊ |
140 | static IOCommandPool *withWorkLoop(IOWorkLoop *inWorkLoop);␊ |
141 | ␊ |
142 | /*!␊ |
143 | * @function init␊ |
144 | * @abstract Should never be used, obsolete. See initWithWorkLoop.␊ |
145 | */␊ |
146 | virtual bool init(IOService *inOwner,␊ |
147 | IOWorkLoop *inWorkLoop,␊ |
148 | UInt32 inSize = kIOCommandPoolDefaultSize);␊ |
149 | ␊ |
150 | /*!␊ |
151 | * @function withWorkLoop␊ |
152 | * @abstract Should never be used, obsolete. See IOCommandPool::withWorkLoop.␊ |
153 | */␊ |
154 | static IOCommandPool *commandPool(IOService *inOwner,␊ |
155 | IOWorkLoop *inWorkLoop,␊ |
156 | UInt32 inSize = kIOCommandPoolDefaultSize);␊ |
157 | ␊ |
158 | ␊ |
159 | /*!␊ |
160 | * @function getCommand␊ |
161 | * @discussion The getCommand method is used to get a pointer to an object of type IOCommand from the pool.␊ |
162 | * @param blockForCommand␊ |
163 | * If the caller would like to have its thread slept until a command is␊ |
164 | * available, it should pass true, else false.␊ |
165 | * @result␊ |
166 | * If the caller passes true in blockForCommand, getCommand guarantees that␊ |
167 | * the result will be a pointer to an IOCommand object from the pool. If␊ |
168 | * the caller passes false, s/he is responsible for checking whether a non-NULL␊ |
169 | * pointer was returned.␊ |
170 | */␊ |
171 | ␊ |
172 | virtual IOCommand *getCommand(bool blockForCommand = true);␊ |
173 | ␊ |
174 | /*!␊ |
175 | * @function returnCommand␊ |
176 | * @discussion␊ |
177 | * The returnCommand method is used to place an object of type IOCommand␊ |
178 | * into the pool, whether it be the first time, or the 1000th time.␊ |
179 | * @param commmand␊ |
180 | * The command to place in the pool.␊ |
181 | */␊ |
182 | ␊ |
183 | virtual void returnCommand(IOCommand *command);␊ |
184 | ␊ |
185 | protected:␊ |
186 | ␊ |
187 | /*!␊ |
188 | * @function gatedGetCommand␊ |
189 | * @discussion␊ |
190 | * The gatedGetCommand method is used to serialize the extraction of a ␊ |
191 | * command from the pool behind a command gate, runAction-ed by getCommand.␊ |
192 | * @param vCommand␊ |
193 | * A pointer to a pointer to an IOCommand object where the returned␊ |
194 | * command will be stored.␊ |
195 | * @param vBlock␊ |
196 | * A bool that indicates whether to block the request until a command␊ |
197 | * becomes available.␊ |
198 | * @result␊ |
199 | * Returns kIOReturnNoResources if no command is available and the client␊ |
200 | * doesn't wish to block until one does become available.␊ |
201 | * kIOReturnSuccess if the vCommand argument is valid.␊ |
202 | */␊ |
203 | virtual IOReturn gatedGetCommand(IOCommand **command, bool blockForCommand);␊ |
204 | ␊ |
205 | /*!␊ |
206 | * @function gatedReturnCommand␊ |
207 | * @discussion␊ |
208 | * The gatedReturnCommand method is used to serialize the return of a ␊ |
209 | * command to the pool behind a command gate, runAction-ed by returnCommand.␊ |
210 | * @param vCommand␊ |
211 | * A pointer to the IOCommand object to be returned to the pool.␊ |
212 | * @result␊ |
213 | * Always returns kIOReturnSuccess if the vCommand argument is valid.␊ |
214 | */␊ |
215 | virtual IOReturn gatedReturnCommand(IOCommand *command);␊ |
216 | ␊ |
217 | private:␊ |
218 | OSMetaClassDeclareReservedUnused(IOCommandPool, 0);␊ |
219 | OSMetaClassDeclareReservedUnused(IOCommandPool, 1);␊ |
220 | OSMetaClassDeclareReservedUnused(IOCommandPool, 2);␊ |
221 | OSMetaClassDeclareReservedUnused(IOCommandPool, 3);␊ |
222 | OSMetaClassDeclareReservedUnused(IOCommandPool, 4);␊ |
223 | OSMetaClassDeclareReservedUnused(IOCommandPool, 5);␊ |
224 | OSMetaClassDeclareReservedUnused(IOCommandPool, 6);␊ |
225 | OSMetaClassDeclareReservedUnused(IOCommandPool, 7);␊ |
226 | };␊ |
227 | ␊ |
228 | #endif␉/* defined(KERNEL) && defined(__cplusplus) */␊ |
229 | ␊ |
230 | #endif␉/* _IOKIT_IO_COMMAND_POOL_H_ */␊ |
231 |