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
75class IOCommandPool : public OSObject
76{
77
78    OSDeclareDefaultStructors(IOCommandPool)
79
80
81protected:
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
114public:
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
185protected:
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
217private:
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