ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

---

IOCommandPool

Overview

Manipulates 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.

---

Functions

commandPool

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

gatedGetCommand

gatedReturnCommand

getCommand

init

Should never be used, obsolete. See initWithWorkLoop.

initWithWorkLoop

Primary initializer for an IOCommandPool object.

returnCommand

withWorkLoop(IOService *, IOWorkLoop *, UInt32)

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

withWorkLoop(IOWorkLoop *)

Primary factory method for the IOCommandPool class

---

commandPool

---

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

public

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

---

gatedGetCommand

---

protected

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

---

protected

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

---

public

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.

public

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

---

initWithWorkLoop

---

Primary initializer for an IOCommandPool object.

public

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

---

public

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.

public

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

---

withWorkLoop(IOWorkLoop *)

---

Primary factory method for the IOCommandPool class

public

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.

Structs and Unions

---

ExpansionData

---

protected

struct ExpansionData {
}; 

Discussion

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

Member Data

---

kIOCommandPoolDefaultSize

---

The default size of any command pool.

protected

static const UInt32 kIOCommandPoolDefaultSize = 2; 

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.

---

reserved

---

protected

ExpansionData *reserved; 

Discussion

Reserved for future use. (Internal use only)

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

 

Last Updated: 2008-12-19