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 Manipulates a pool of commands which inherit from IOCommand.
  59  * @discussion
  60  * The IOCommandPool class is used to manipulate a pool of commands which
  61  * inherit from IOCommand. It includes a factory method to create a pool
  62  * of a certain size. Once the factory method is invoked, the semaphore
  63  * is set to zero. The caller must then put commands in the pool by creating
  64  * the command (via the controller's factory method or a memory allocation)
  65  * and calling the returnCommand method with the newly created command as its
  66  * argument.
  67  */
  68
  69 class IOCommandPool : public OSObject
  70 {
  71
  72     OSDeclareDefaultStructors(IOCommandPool)
  73
  74
  75 protected:
  76
  77     queue_head_t fQueueHead;    /* head of the queue of elements available */
  78     UInt32 fSleepers;           /* Count of threads sleeping on this pool */
  79     IOCommandGate *fSerializer; /* command gate used for serializing pool access */
  80
  81 /*! @struct ExpansionData
  82     @discussion This structure will be used to expand the capablilties of the IOEventSource in the future.
  83     */
  84     struct ExpansionData { };
  85
  86 /*! @var reserved
  87     Reserved for future use.  (Internal use only)  */
  88     ExpansionData *reserved;
  89
  90     /*!
  91      * @const kIOCommandPoolDefaultSize
  92      * @abstract The default size of any command pool.
  93      * @discussion
  94      * kIOCommandPoolDefaultSize is the default size of any command pool.
  95      * The default size was determined to be the smallest size for which
  96      * a pool makes sense.
  97      */
  98
  99     static const UInt32 kIOCommandPoolDefaultSize = 2;
 100
 101     /*
 102      * Free all of this object's outstanding resources.
 103      */
 104
 105     virtual void free(void);
 106
 107
 108 public:
 109
 110     /*!
 111      * @function initWithWorkLoop
 112      * @abstract Primary initializer for an IOCommandPool object.
 113      * @discussion Primary initializer for an IOCommandPool.
 114      * Should probably use IOCommandPool::withWorkLoop() as it is easier to use.
 115      * @param inWorkLoop
 116      * The workloop that this command pool should synchronize with.
 117      * @result Returns true if command pool was successfully initialized.
 118      */
 119     virtual bool initWithWorkLoop(IOWorkLoop *workLoop);
 120
 121     /*!
 122      * @function withWorkLoop
 123      * @abstract Primary factory method for the IOCommandPool class
 124      * @discussion
 125      * The withWorkLoop method is what is known as a factory method. It creates
 126      * a new instance of an IOCommandPool and returns a pointer to that object.
 127      * @param inWorkLoop
 128      * The workloop that this command pool should synchronize with.
 129      * @result
 130      * Returns a pointer to an instance of IOCommandPool if successful,
 131      * otherwise NULL.
 132      */
 133
 134     static IOCommandPool *withWorkLoop(IOWorkLoop *inWorkLoop);
 135
 136     /*!
 137      * @function init
 138      * @abstract Should never be used, obsolete. See initWithWorkLoop.
 139      */
 140     virtual bool init(IOService *inOwner,
 141                       IOWorkLoop *inWorkLoop,
 142                       UInt32 inSize = kIOCommandPoolDefaultSize);
 143
 144     /*!
 145      * @function withWorkLoop
 146      * @abstract Should never be used, obsolete. See IOCommandPool::withWorkLoop.
 147      */
 148     static IOCommandPool *commandPool(IOService *inOwner,
 149                                         IOWorkLoop *inWorkLoop,
 150                                         UInt32 inSize = kIOCommandPoolDefaultSize);
 151
 152
 153     /*!
 154      * @function getCommand
 155      * @discussion The getCommand method is used to get a pointer to an object of type IOCommand from the pool.
 156      * @param blockForCommand
 157      * If the caller would like to have its thread slept until a command is
 158      * available, it should pass true, else false.
 159      * @result
 160      * If the caller passes true in blockForCommand, getCommand guarantees that
 161      * the result will be a pointer to an IOCommand object from the pool. If
 162      * the caller passes false, s/he is responsible for checking whether a non-NULL
 163      * pointer was returned.
 164      */
 165
 166     virtual IOCommand *getCommand(bool blockForCommand = true);
 167
 168     /*!
 169      * @function returnCommand
 170      * @discussion
 171      * The returnCommand method is used to place an object of type IOCommand
 172      * into the pool, whether it be the first time, or the 1000th time.
 173      * @param commmand
 174      * The command to place in the pool.
 175      */
 176
 177     virtual void returnCommand(IOCommand *command);
 178
 179 protected:
 180
 181     /*!
 182      * @function gatedGetCommand
 183      * @discussion
 184      * The gatedGetCommand method is used to serialize the extraction of a
 185      * command from the pool behind a command gate, runAction-ed by getCommand.
 186      * @param vCommand
 187      * A pointer to a pointer to an IOCommand object where the returned
 188      * command will be stored.
 189      * @param vBlock
 190      * A bool that indicates whether to block the request until a command
 191      * becomes available.
 192      * @result
 193      * Returns kIOReturnNoResources if no command is available and the client
 194      * doesn't wish to block until one does become available.
 195      * kIOReturnSuccess if the vCommand argument is valid.
 196      */
 197     virtual IOReturn gatedGetCommand(IOCommand **command, bool blockForCommand);
 198
 199     /*!
 200      * @function gatedReturnCommand
 201      * @discussion
 202      * The gatedReturnCommand method is used to serialize the return of a
 203      * command to the pool behind a command gate, runAction-ed by returnCommand.
 204      * @param vCommand
 205      * A pointer to the IOCommand object to be returned to the pool.
 206      * @result
 207      * Always returns kIOReturnSuccess if the vCommand argument is valid.
 208      */
 209     virtual IOReturn gatedReturnCommand(IOCommand *command);
 210
 211 private:
 212     OSMetaClassDeclareReservedUnused(IOCommandPool, 0);
 213     OSMetaClassDeclareReservedUnused(IOCommandPool, 1);
 214     OSMetaClassDeclareReservedUnused(IOCommandPool, 2);
 215     OSMetaClassDeclareReservedUnused(IOCommandPool, 3);
 216     OSMetaClassDeclareReservedUnused(IOCommandPool, 4);
 217     OSMetaClassDeclareReservedUnused(IOCommandPool, 5);
 218     OSMetaClassDeclareReservedUnused(IOCommandPool, 6);
 219     OSMetaClassDeclareReservedUnused(IOCommandPool, 7);
 220 };
 221
 222 #endif  /* defined(KERNEL) && defined(__cplusplus) */
 223
 224 #endif  /* _IOKIT_IO_COMMAND_POOL_H_ */