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

IOCommandGate

Inherits from:	IOEventSource
Declared In:	IOCommandGate.h

Overview

Single-threaded work-loop client request mechanism.

Discussion

An IOCommandGate instance is an extremely lightweight mechanism that executes an action on the driver's work-loop. 'On the work-loop' is actually a lie but the work-loop single threaded semantic is maintained for this event source. Using the work-loop gate rather than execution by the workloop. The command gate tests for a potential self dead lock by checking if the runCommand request is made from the work-loop's thread, it doens't check for a mutual dead lock though where a pair of work loop's dead lock each other.

The IOCommandGate is a lighter weight version of the IOCommandQueue and should be used in preference. Generally use a command queue whenever you need a client to submit a request to a work loop. A typical command gate action would check if the hardware is active, if so it will add the request to a pending queue internal to the device or the device's family. Otherwise if the hardware is inactive then this request can be acted upon immediately.

CAUTION: The runAction and runCommand functions can not be called from an interrupt context.

Functions

attemptAction: Single thread a call to an action with the target work-loop.
attemptCommand: Single thread a command with the target work-loop.
checkForWork: Not used, $link IOEventSource::checkForWork().
commandGate: Factory method to create and initialise an IOCommandGate, See $link init.
commandSleep: Put a thread that is currently holding the command gate to sleep.
commandWakeup: Wakeup one or more threads that are asleep on an event.
disable: Disable the command gate
enable: Enable command gate, this will unblock any blocked Commands and Actions.
init: Class initialiser.
runAction: Single thread a call to an action with the target work-loop.
runCommand: Single thread a command with the target work-loop.

attemptAction

Single thread a call to an action with the target work-loop.

public

virtual IOReturn attemptAction(
    Action action, 
    void *arg0 = 0,
    void *arg1 = 0, 
    void *arg2 = 0,
    void *arg3 = 0);

Parameters

action: Pointer to function to be executed in work-loop context.
arg0: Parameter for action parameter, defaults to 0.
arg1: Parameter for action parameter, defaults to 0.
arg2: Parameter for action parameter, defaults to 0.
arg3: Parameter for action parameter, defaults to 0.

Return Value

kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNotPermitted if this event source is currently disabled, kIOReturnCannotLock if lock attempt fails.

Discussion

Client function that causes the given action to be called in a single threaded manner. Beware the work-loop's gate is recursive and command gates can cause direct or indirect re-entrancy. When the executing on a client's thread attemptCommand will fail if the work-loop's gate is open.

attemptCommand

Single thread a command with the target work-loop.

public

virtual IOReturn attemptCommand(
    void *arg0 = 0,
    void *arg1 = 0, 
    void *arg2 = 0,
    void *arg3 = 0);

Parameters

arg0: Parameter for action of command gate, defaults to 0.
arg1: Parameter for action of command gate, defaults to 0.
arg2: Parameter for action of command gate, defaults to 0.
arg3: Parameter for action of command gate, defaults to 0.

Return Value

kIOReturnSuccess if successful. kIOReturnNotPermitted if this event source is currently disabled, kIOReturnNoResources if no action available, kIOReturnCannotLock if lock attempt fails.

Discussion

Client function that causes the current action to be called in a single threaded manner. Beware the work-loop's gate is recursive and command gates can cause direct or indirect re-entrancy. When the executing on a client's thread attemptCommand will fail if the work-loop's gate is open.

checkForWork

Not used, $link IOEventSource::checkForWork().

protected

virtual bool checkForWork();

commandGate

Factory method to create and initialise an IOCommandGate, See $link init.

public

static IOCommandGate *commandGate(
    OSObject *owner,
    Action action = 0);

Return Value

Returns a pointer to the new command gate if sucessful, 0 otherwise.

commandSleep

Put a thread that is currently holding the command gate to sleep.

public

virtual IOReturn commandSleep(
    void *event, 
    UInt32 interruptible = THREAD_ABORTSAFE);

Parameters

event: Pointer to an address.
interruptible: THREAD_UNINT, THREAD_INTERRUPTIBLE or THREAD_ABORTSAFE, defaults to THREAD_ABORTSAFE.

Return Value

THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted by clear_wait, THREAD_RESTART - restart operation entirely, kIOReturnNotPermitted if the calling thread does not hold the command gate.

Discussion

Put a thread to sleep waiting for an event but release the gate first. If the event occurs then the commandGate is closed before the returns.

commandWakeup

Wakeup one or more threads that are asleep on an event.

public

virtual void commandWakeup(
    void *event,
    bool oneThread = false);

Parameters

event: Pointer to an address.
onlyOneThread: true to only wake up at most one thread, false otherwise.

disable

Disable the command gate

public

virtual void disable();

Discussion

When a command gate is disabled all future calls to runAction and runCommand will stall until the gate is enable()d later. This can be used to block client threads when a system sleep is requested. The IOWorkLoop thread itself will never stall, even when making runAction/runCommand calls. This call must be made from a gated context, to clear potential race conditions.

enable

Enable command gate, this will unblock any blocked Commands and Actions.

public

virtual void enable();

Discussion

Enable the command gate. The attemptAction/attemptCommand calls will now be enabled and can succeeed. Stalled runCommand/runAction calls will be woken up.

init

Class initialiser.

public

virtual bool init(
    OSObject *owner,
    Action action = 0);

Parameters

owner: Owner of this, newly created, instance of the IOCommandGate. This argument will be used as the first parameter in the action callout.
action: Pointer to a C function that is called whenever a client of the IOCommandGate calls runCommand. NB Can be a C++ member function but caller must cast the member function to $link IOCommandGate::Action and they will get a compiler warning. Defaults to zero, see $link IOEventSource::setAction.

Return Value

True if inherited classes initialise successfully.

Discussion

Initialiser for IOCommandGate operates only on newly 'newed' objects. Shouldn't be used to re-init an existing instance.

runAction

Single thread a call to an action with the target work-loop.

public

virtual IOReturn runAction(
    Action action, 
    void *arg0 = 0,
    void *arg1 = 0, 
    void *arg2 = 0,
    void *arg3 = 0);

Parameters

action: Pointer to function to be executed in work-loop context.
arg0: Parameter for action parameter, defaults to 0.
arg1: Parameter for action parameter, defaults to 0.
arg2: Parameter for action parameter, defaults to 0.
arg3: Parameter for action parameter, defaults to 0.

Return Value

kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNotPermitted if this event source is currently disabled.

Discussion

Client function that causes the given action to be called in a single threaded manner. Beware the work-loop's gate is recursive and command gates can cause direct or indirect re-entrancy. When the executing on a client's thread runAction will sleep until the work-loop's gate opens for execution of client actions, the action is single threaded against all other work-loop event sources.

runCommand

Single thread a command with the target work-loop.

public

virtual IOReturn runCommand(
    void *arg0 = 0,
    void *arg1 = 0, 
    void *arg2 = 0,
    void *arg3 = 0);

Parameters

arg0: Parameter for action of command gate, defaults to 0.
arg1: Parameter for action of command gate, defaults to 0.
arg2: Parameter for action of command gate, defaults to 0.
arg3: Parameter for action of command gate, defaults to 0.

Return Value

kIOReturnSuccess if successful. kIOReturnNotPermitted if this event source is currently disabled, kIOReturnNoResources if no action available.

Discussion

Client function that causes the current action to be called in a single threaded manner. Beware the work-loop's gate is recursive and command gates can cause direct or indirect re-entrancy. When the executing on a client's thread runCommand will sleep until the work-loop's gate opens for execution of client actions, the action is single threaded against all other work-loop event sources.

Typedefs

Action

public

typedef IOReturn ( *Action)(
    OSObject *owner, 
    void *arg0,
    void *arg1, 
    void *arg2,
    void *arg3);

Fields

owner: Target of the function, can be used as a refcon. The owner is set during initialisation of the IOCommandGate instance. Note if a C++ function was specified this parameter is implicitly the first paramter in the target member function's parameter list.
arg0: Argument to action from run operation.
arg1: Argument to action from run operation.
arg2: Argument to action from run operation.
arg3: Argument to action from run operation.

Discussion

Type and arguments of callout C function that is used when a runCommand is executed by a client. Cast to this type when you want a C++ member function to be used. Note the arg1 - arg3 parameters are straight pass through from the runCommand to the action callout.

Structs and Unions

ExpansionData

protected

struct ExpansionData {
};

Discussion

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

Member Data

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