iokit/IOKit/IOCommandPool.h

   1 /*
   2  * Copyright (c) 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 /*
  24  *
  25  *      Copyright (c) 2000 Apple Computer, Inc.  All rights reserved.
  26  *
  27  *      HISTORY
  28  *
  29  *      2001-01-17      gvdl    Re-implement on IOCommandGate::commandSleep
  30  *      11/13/2000      CJS     Created IOCommandPool class and implementation
  31  *
  32  */
  33
  34 /*!
  35  * @header IOCommandPool
  36  * @abstract
  37  * This header contains the IOCommandPool class definition.
  38  */
  39
  40 #ifndef _IOKIT_IO_COMMAND_POOL_H_
  41 #define _IOKIT_IO_COMMAND_POOL_H_
  42
  43 /*
  44  * Kernel
  45  */
  46
  47 #if defined(KERNEL) && defined(__cplusplus)
  48
  49 #include <kern/kern_types.h>
  50 #include <kern/queue.h>
  51 #include <IOKit/IOCommand.h>
  52 #include <IOKit/IOCommandGate.h>
  53 #include <IOKit/IOService.h>
  54 #include <IOKit/IOWorkLoop.h>
  55
  56 /*!
  57  * @class IOCommandPool
  58  * @abstract
  59  * The IOCommandPool class is used to manipulate a pool of commands which
  60  * inherit from IOCommand.
  61  * @discussion
  62  * The IOCommandPool class is used to manipulate a pool of commands which
  63  * inherit from IOCommand. It includes a factory method to create a pool
  64  * of a certain size. Once the factory method is invoked, the semaphore
  65  * is set to zero. The caller must then put commands in the pool by creating
  66  * the command (via the controller's factory method or a memory allocation)
  67  * and calling the returnCommand method with the newly created command as its
  68  * argument.
  69  */
  70
  71 class IOCommandPool : public OSObject
  72 {
  73
  74     OSDeclareDefaultStructors(IOCommandPool)
  75
  76
  77 protected:
  78
  79     queue_head_t fQueueHead;    /* head of the queue of elements available */
  80     UInt32 fSleepers;           /* Count of threads sleeping on this pool */
  81     IOCommandGate *fSerializer; /* command gate used for serializing pool access */
  82
  83 /*! @struct ExpansionData
  84     @discussion This structure will be used to expand the capablilties of the IOEventSource in the future.
  85     */
  86     struct ExpansionData { };
  87
  88 /*! @var reserved
  89     Reserved for future use.  (Internal use only)  */
  90     ExpansionData *reserved;
  91
  92     /*!
  93      * @defined kIOCommandPoolDefaultSize
  94      * @abstract
  95      * kIOCommandPoolDefaultSize is the default size of any command pool.
  96      * @discussion
  97      * kIOCommandPoolDefaultSize is the default size of any command pool.
  98      * The default size was determined to be the smallest size for which
  99      * a pool makes sense.
 100      */
 101
 102     static const UInt32 kIOCommandPoolDefaultSize = 2;
 103
 104     /*
 105      * Free all of this object's outstanding resources.
 106      */
 107
 108     virtual void free(void);
 109
 110
 111 public:
 112
 113     /*!
 114      * @function initWithWorkLoop
 115      * @abstract Primary initialiser for an IOCommandPool Object
 116      * @discussion Primary initialiser for an IOCommandPool.
 117      * Should probably use IOCommandPool::withWorkLoop() as it is easier to use.
 118      * @param inWorkLoop
 119      * The workloop that this command pool should synchronise with.
 120      * @result true if command pool was sucessfully initialised.
 121      */
 122     virtual bool initWithWorkLoop(IOWorkLoop *workLoop);
 123
 124     /*!
 125      * @function withWorkLoop
 126      * @abstract Primary factory method for the IOCommandPool class
 127      * @discussion
 128      * The withWorkLoop method is what is known as a factory method. It creates
 129      * a new instance of an IOCommandPool and returns a pointer to that object.
 130      * @param inWorkLoop
 131      * The workloop that this command pool should synchronise with.
 132      * @result
 133      * Returns a pointer to an instance of IOCommandPool if successful,
 134      * otherwise NULL.
 135      */
 136
 137     static IOCommandPool *withWorkLoop(IOWorkLoop *inWorkLoop);
 138
 139     /*!
 140      * @function init
 141      * @abstract Should never be used, obsolete See initWithWorkLoop
 142      */
 143     virtual bool init(IOService *inOwner,
 144                       IOWorkLoop *inWorkLoop,
 145                       UInt32 inSize = kIOCommandPoolDefaultSize);
 146
 147     /*!
 148      * @function withWorkLoop
 149      * @abstract Should never be used, obsolete See IOCommandPool::withWorkLoop
 150      */
 151     static IOCommandPool *commandPool(IOService *inOwner,
 152                                         IOWorkLoop *inWorkLoop,
 153                                         UInt32 inSize = kIOCommandPoolDefaultSize);
 154
 155
 156     /*!
 157      * @function getCommand
 158      * @discussion
 159      * The getCommand method is used to get a pointer to an object of type IOCommand
 160      * from the pool.
 161      * @param blockForCommand
 162      * If the caller would like to have its thread slept until a command is
 163      * available, it should pass true, else false
 164      * @result
 165      * If the caller passes true in blockForCommand, getCommand guarantees that
 166      * the result will be a pointer to an IOCommand object from the pool. If
 167      * the caller passes false, s/he is responsible for checking whether a non-NULL
 168      * pointer was returned.
 169      */
 170
 171     virtual IOCommand *getCommand(bool blockForCommand = true);
 172
 173     /*!
 174      * @function returnCommand
 175      * @discussion
 176      * The returnCommand method is used to place an object of type IOCommand
 177      * into the pool, whether it be the first time, or the 1000th time.
 178      * @param commmand
 179      * The command to place in the pool.
 180      */
 181
 182     virtual void returnCommand(IOCommand *command);
 183
 184 protected:
 185
 186     /*!
 187      * @function gatedGetCommand
 188      * @discussion
 189      * The gatedGetCommand method is used to serialize the extraction of a
 190      * command of from the pool behind a command gate.
 191      * 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 with 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 of to the pool behind a command gate.
 210      * runAction-ed by returnCommand.
 211      * @param vCommand
 212      * A pointer to the IOCommand object to be returned to the pool.
 213      * @result
 214      * Always returns kIOReturnSuccess if the vCommand argument is valid.
 215      */
 216     virtual IOReturn gatedReturnCommand(IOCommand *command);
 217
 218 private:
 219     OSMetaClassDeclareReservedUnused(IOCommandPool, 0);
 220     OSMetaClassDeclareReservedUnused(IOCommandPool, 1);
 221     OSMetaClassDeclareReservedUnused(IOCommandPool, 2);
 222     OSMetaClassDeclareReservedUnused(IOCommandPool, 3);
 223     OSMetaClassDeclareReservedUnused(IOCommandPool, 4);
 224     OSMetaClassDeclareReservedUnused(IOCommandPool, 5);
 225     OSMetaClassDeclareReservedUnused(IOCommandPool, 6);
 226     OSMetaClassDeclareReservedUnused(IOCommandPool, 7);
 227 };
 228
 229 #endif  /* defined(KERNEL) && defined(__cplusplus) */
 230
 231 #endif  /* _IOKIT_IO_COMMAND_POOL_H_ */