/* * Copyright (c) 2000 Apple Computer, Inc. All rights reserved. * * @APPLE_LICENSE_HEADER_START@ * * The contents of this file constitute Original Code as defined in and * are subject to the Apple Public Source License Version 1.1 (the * "License"). You may not use this file except in compliance with the * License. Please obtain a copy of the License at * http://www.apple.com/publicsource and read it before using this file. * * This Original Code and all software distributed under the License are * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the * License for the specific language governing rights and limitations * under the License. * * @APPLE_LICENSE_HEADER_END@ */ /* * * Copyright (c) 2000 Apple Computer, Inc. All rights reserved. * * HISTORY * * 2001-01-17 gvdl Re-implement on IOCommandGate::commandSleep * 11/13/2000 CJS Created IOCommandPool class and implementation * */ /*! * @header IOCommandPool * @abstract * This header contains the IOCommandPool class definition. */ #ifndef _IOKIT_IO_COMMAND_POOL_H_ #define _IOKIT_IO_COMMAND_POOL_H_ /* * Kernel */ #if defined(KERNEL) && defined(__cplusplus) #include <kern/kern_types.h> #include <kern/queue.h> #include <IOKit/IOCommand.h> #include <IOKit/IOCommandGate.h> #include <IOKit/IOService.h> #include <IOKit/IOWorkLoop.h> /*! * @class IOCommandPool * @abstract * The IOCommandPool class is used to manipulate a pool of commands which * inherit from IOCommand. * @discussion * The IOCommandPool class is used to manipulate a pool of commands which * inherit from IOCommand. It includes a factory method to create a pool * of a certain size. Once the factory method is invoked, the semaphore * is set to zero. The caller must then put commands in the pool by creating * the command (via the controller's factory method or a memory allocation) * and calling the returnCommand method with the newly created command as its * argument. */ class IOCommandPool : public OSObject { OSDeclareDefaultStructors(IOCommandPool) protected: queue_head_t fQueueHead; /* head of the queue of elements available */ UInt32 fSleepers; /* Count of threads sleeping on this pool */ IOCommandGate *fSerializer; /* command gate used for serializing pool access */ /*! @struct ExpansionData @discussion This structure will be used to expand the capablilties of the IOEventSource in the future. */ struct ExpansionData { }; /*! @var reserved Reserved for future use. (Internal use only) */ ExpansionData *reserved; /*! * @defined kIOCommandPoolDefaultSize * @abstract * kIOCommandPoolDefaultSize is the default size of any command pool. * @discussion * kIOCommandPoolDefaultSize is the default size of any command pool. * The default size was determined to be the smallest size for which * a pool makes sense. */ static const UInt32 kIOCommandPoolDefaultSize = 2; /* * Free all of this object's outstanding resources. */ virtual void free(void); public: /*! * @function initWithWorkLoop * @abstract Primary initialiser for an IOCommandPool Object * @discussion Primary initialiser for an IOCommandPool. * Should probably use IOCommandPool::withWorkLoop() as it is easier to use. * @param inWorkLoop * The workloop that this command pool should synchronise with. * @result true if command pool was sucessfully initialised. */ virtual bool initWithWorkLoop(IOWorkLoop *workLoop); /*! * @function withWorkLoop * @abstract Primary factory method for the IOCommandPool class * @discussion * The withWorkLoop method is what is known as a factory method. It creates * a new instance of an IOCommandPool and returns a pointer to that object. * @param inWorkLoop * The workloop that this command pool should synchronise with. * @result * Returns a pointer to an instance of IOCommandPool if successful, * otherwise NULL. */ static IOCommandPool *withWorkLoop(IOWorkLoop *inWorkLoop); /*! * @function init * @abstract Should never be used, obsolete See initWithWorkLoop */ virtual bool init(IOService *inOwner, IOWorkLoop *inWorkLoop, UInt32 inSize = kIOCommandPoolDefaultSize); /*! * @function withWorkLoop * @abstract Should never be used, obsolete See IOCommandPool::withWorkLoop */ static IOCommandPool *commandPool(IOService *inOwner, IOWorkLoop *inWorkLoop, UInt32 inSize = kIOCommandPoolDefaultSize); /*! * @function getCommand * @discussion * The getCommand method is used to get a pointer to an object of type IOCommand * from the pool. * @param blockForCommand * If the caller would like to have its thread slept until a command is * available, it should pass true, else false * @result * If the caller passes true in blockForCommand, getCommand guarantees that * the result will be a pointer to an IOCommand object from the pool. If * the caller passes false, s/he is responsible for checking whether a non-NULL * pointer was returned. */ virtual IOCommand *getCommand(bool blockForCommand = true); /*! * @function returnCommand * @discussion * The returnCommand method is used to place an object of type IOCommand * into the pool, whether it be the first time, or the 1000th time. * @param commmand * The command to place in the pool. */ virtual void returnCommand(IOCommand *command); protected: /*! * @function gatedGetCommand * @discussion * The gatedGetCommand method is used to serialize the extraction of a * command of from the pool behind a command gate. * runAction-ed by getCommand. * @param vCommand * A pointer to a pointer to an IOCommand object where the returned * command will be stored * @param vBlock * A bool that indicates whether to block the request until a command * becomes available. * @result * Returns kIOReturnNoResources if no command is available and the client * doesn't with to block until one does become available. * kIOReturnSuccess if the vCommand argument is valid. */ virtual IOReturn gatedGetCommand(IOCommand **command, bool blockForCommand); /*! * @function gatedReturnCommand * @discussion * The gatedReturnCommand method is used to serialize the return of a * command of to the pool behind a command gate. * runAction-ed by returnCommand. * @param vCommand * A pointer to the IOCommand object to be returned to the pool. * @result * Always returns kIOReturnSuccess if the vCommand argument is valid. */ virtual IOReturn gatedReturnCommand(IOCommand *command); private: OSMetaClassDeclareReservedUnused(IOCommandPool, 0); OSMetaClassDeclareReservedUnused(IOCommandPool, 1); OSMetaClassDeclareReservedUnused(IOCommandPool, 2); OSMetaClassDeclareReservedUnused(IOCommandPool, 3); OSMetaClassDeclareReservedUnused(IOCommandPool, 4); OSMetaClassDeclareReservedUnused(IOCommandPool, 5); OSMetaClassDeclareReservedUnused(IOCommandPool, 6); OSMetaClassDeclareReservedUnused(IOCommandPool, 7); }; #endif /* defined(KERNEL) && defined(__cplusplus) */ #endif /* _IOKIT_IO_COMMAND_POOL_H_ */