iokit/IOKit/IOCommandPool.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25
  26 /*
  27  *
  28  *      Copyright (c) 2000 Apple Computer, Inc.  All rights reserved.
  29  *
  30  *      HISTORY
  31  *
  32  *      2001-01-17      gvdl    Re-implement on IOCommandGate::commandSleep
  33  *      11/13/2000      CJS     Created IOCommandPool class and implementation
  34  *
  35  */
  36
  37 /*!
  38  * @header IOCommandPool
  39  * @abstract
  40  * This header contains the IOCommandPool class definition.
  41  */
  42
  43 #ifndef _IOKIT_IO_COMMAND_POOL_H_
  44 #define _IOKIT_IO_COMMAND_POOL_H_
  45
  46 /*
  47  * Kernel
  48  */
  49
  50 #if defined(KERNEL) && defined(__cplusplus)
  51
  52 #include <kern/kern_types.h>
  53 #include <kern/queue.h>
  54 #include <IOKit/IOCommand.h>
  55 #include <IOKit/IOCommandGate.h>
  56 #include <IOKit/IOService.h>
  57 #include <IOKit/IOWorkLoop.h>
  58
  59 /*!
  60  * @class IOCommandPool
  61  * @abstract
  62  * The IOCommandPool class is used to manipulate a pool of commands which
  63  * inherit from IOCommand.
  64  * @discussion
  65  * The IOCommandPool class is used to manipulate a pool of commands which
  66  * inherit from IOCommand. It includes a factory method to create a pool
  67  * of a certain size. Once the factory method is invoked, the semaphore
  68  * is set to zero. The caller must then put commands in the pool by creating
  69  * the command (via the controller's factory method or a memory allocation)
  70  * and calling the returnCommand method with the newly created command as its
  71  * argument.
  72  */
  73
  74 class IOCommandPool : public OSObject
  75 {
  76
  77     OSDeclareDefaultStructors(IOCommandPool)
  78
  79
  80 protected:
  81
  82     queue_head_t fQueueHead;    /* head of the queue of elements available */
  83     UInt32 fSleepers;           /* Count of threads sleeping on this pool */
  84     IOCommandGate *fSerializer; /* command gate used for serializing pool access */
  85
  86 /*! @struct ExpansionData
  87     @discussion This structure will be used to expand the capablilties of the IOEventSource in the future.
  88     */
  89     struct ExpansionData { };
  90
  91 /*! @var reserved
  92     Reserved for future use.  (Internal use only)  */
  93     ExpansionData *reserved;
  94
  95     /*!
  96      * @defined kIOCommandPoolDefaultSize
  97      * @abstract
  98      * kIOCommandPoolDefaultSize is 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 initialiser for an IOCommandPool Object
 119      * @discussion Primary initialiser 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 synchronise with.
 123      * @result true if command pool was sucessfully initialised.
 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 synchronise 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
 162      * The getCommand method is used to get a pointer to an object of type IOCommand
 163      * from the pool.
 164      * @param blockForCommand
 165      * If the caller would like to have its thread slept until a command is
 166      * available, it should pass true, else false
 167      * @result
 168      * If the caller passes true in blockForCommand, getCommand guarantees that
 169      * the result will be a pointer to an IOCommand object from the pool. If
 170      * the caller passes false, s/he is responsible for checking whether a non-NULL
 171      * pointer was returned.
 172      */
 173
 174     virtual IOCommand *getCommand(bool blockForCommand = true);
 175
 176     /*!
 177      * @function returnCommand
 178      * @discussion
 179      * The returnCommand method is used to place an object of type IOCommand
 180      * into the pool, whether it be the first time, or the 1000th time.
 181      * @param commmand
 182      * The command to place in the pool.
 183      */
 184
 185     virtual void returnCommand(IOCommand *command);
 186
 187 protected:
 188
 189     /*!
 190      * @function gatedGetCommand
 191      * @discussion
 192      * The gatedGetCommand method is used to serialize the extraction of a
 193      * command of from the pool behind a command gate.
 194      * runAction-ed by getCommand.
 195      * @param vCommand
 196      * A pointer to a pointer to an IOCommand object where the returned
 197      * command will be stored
 198      * @param vBlock
 199      * A bool that indicates whether to block the request until a command
 200      * becomes available.
 201      * @result
 202      * Returns kIOReturnNoResources if no command is available and the client
 203      * doesn't with to block until one does become available.
 204      * kIOReturnSuccess if the vCommand argument is valid.
 205      */
 206     virtual IOReturn gatedGetCommand(IOCommand **command, bool blockForCommand);
 207
 208     /*!
 209      * @function gatedReturnCommand
 210      * @discussion
 211      * The gatedReturnCommand method is used to serialize the return of a
 212      * command of to the pool behind a command gate.
 213      * runAction-ed by returnCommand.
 214      * @param vCommand
 215      * A pointer to the IOCommand object to be returned to the pool.
 216      * @result
 217      * Always returns kIOReturnSuccess if the vCommand argument is valid.
 218      */
 219     virtual IOReturn gatedReturnCommand(IOCommand *command);
 220
 221 private:
 222     OSMetaClassDeclareReservedUnused(IOCommandPool, 0);
 223     OSMetaClassDeclareReservedUnused(IOCommandPool, 1);
 224     OSMetaClassDeclareReservedUnused(IOCommandPool, 2);
 225     OSMetaClassDeclareReservedUnused(IOCommandPool, 3);
 226     OSMetaClassDeclareReservedUnused(IOCommandPool, 4);
 227     OSMetaClassDeclareReservedUnused(IOCommandPool, 5);
 228     OSMetaClassDeclareReservedUnused(IOCommandPool, 6);
 229     OSMetaClassDeclareReservedUnused(IOCommandPool, 7);
 230 };
 231
 232 #endif  /* defined(KERNEL) && defined(__cplusplus) */
 233
 234 #endif  /* _IOKIT_IO_COMMAND_POOL_H_ */