IOCommandPool

Inherits from
OSObject
Availability
Available in OS X v10.6 and later.
Declared in
IOCommandPool.h

Overview

Manipulates a pool of commands which inherit from IOCommand.

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.

Tasks

Miscellaneous

Instance Methods

commandPool

Should never be used, obsolete. See IOCommandPool::withWorkLoop.

static IOCommandPool *commandPool( IOService *inOwner, IOWorkLoop *inWorkLoop, UInt32 inSize = kIOCommandPoolDefaultSize);

gatedGetCommand

virtual IOReturn gatedGetCommand( IOCommand **command, bool blockForCommand);
Parameters
vCommand

A pointer to a pointer to an IOCommand object where the returned command will be stored.

vBlock

A bool that indicates whether to block the request until a command becomes available.

Return Value

Returns kIOReturnNoResources if no command is available and the client doesn't wish to block until one does become available. kIOReturnSuccess if the vCommand argument is valid.

Discussion

The gatedGetCommand method is used to serialize the extraction of a command from the pool behind a command gate, runAction-ed by getCommand.

gatedReturnCommand

virtual IOReturn gatedReturnCommand( IOCommand *command);
Parameters
vCommand

A pointer to the IOCommand object to be returned to the pool.

Return Value

Always returns kIOReturnSuccess if the vCommand argument is valid.

Discussion

The gatedReturnCommand method is used to serialize the return of a command to the pool behind a command gate, runAction-ed by returnCommand.

getCommand

virtual IOCommand *getCommand( bool blockForCommand = true);
Parameters
blockForCommand

If the caller would like to have its thread slept until a command is available, it should pass true, else false.

Return Value

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.

Discussion

The getCommand method is used to get a pointer to an object of type IOCommand from the pool.

init

Should never be used, obsolete. See initWithWorkLoop.

virtual bool init( IOService *inOwner, IOWorkLoop *inWorkLoop, UInt32 inSize = kIOCommandPoolDefaultSize);

initWithWorkLoop

Primary initializer for an IOCommandPool object.

virtual bool initWithWorkLoop( IOWorkLoop *workLoop);
Parameters
inWorkLoop

The workloop that this command pool should synchronize with.

Return Value

Returns true if command pool was successfully initialized.

Discussion

Primary initializer for an IOCommandPool. Should probably use IOCommandPool::withWorkLoop() as it is easier to use.

returnCommand

virtual void returnCommand( IOCommand *command);
Parameters
commmand

The command to place in the pool.

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.

withWorkLoop(IOService *, IOWorkLoop *, UInt32)

Should never be used, obsolete. See IOCommandPool::withWorkLoop.

static IOCommandPool *commandPool( IOService *inOwner, IOWorkLoop *inWorkLoop, UInt32 inSize = kIOCommandPoolDefaultSize);

withWorkLoop(IOWorkLoop *)

Primary factory method for the IOCommandPool class

static IOCommandPool *withWorkLoop( IOWorkLoop *inWorkLoop);
Parameters
inWorkLoop

The workloop that this command pool should synchronize with.

Return Value

Returns a pointer to an instance of IOCommandPool if successful, otherwise NULL.

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.

Constants

kIOCommandPoolDefaultSize
static const UInt32 kIOCommandPoolDefaultSize = 2;

The default size of any command pool.

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.

ExpansionData

struct ExpansionData {
};
Discussion

This structure will be used to expand the capablilties of the IOEventSource in the future.

Instance Variables

reserved

ExpansionData *reserved;

Reserved for future use. (Internal use only)