/*
 * 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_ */