IOCommandGate

Inherits from:
Declared In:

Overview

Single-threaded work-loop client request mechanism.

Discussion

An IOCommandGate instance is an extremely light way 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 doesn'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, runCommand, and attemptCommand functions cannot 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(void *, AbsoluteTime, UInt32)

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

commandSleep(void *, UInt32)

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

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. When the executing on a client's thread attemptCommand will fail if the work-loop's gate is closed.

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(void *, AbsoluteTime, UInt32)

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

public

virtual IOReturn commandSleep(
    void *event, 
    AbsoluteTime deadline, 
    UInt32 interruptible);
Parameters
event

Pointer to an address.

deadline

Clock deadline to timeout the sleep.

interruptible

THREAD_UNINT, THREAD_INTERRUPTIBLE or THREAD_ABORTSAFE. THREAD_UNINT specifies that the sleep cannot be interrupted by a signal. THREAD_INTERRUPTIBLE specifies that the sleep may be interrupted by a "kill -9" signal. THREAD_ABORTSAFE specifies that the sleep may be interrupted by any user signal.

Return Value

THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted, 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 or timeout occurs then the commandGate is closed before the function returns.

commandSleep(void *, UInt32)

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. THREAD_UNINT specifies that the sleep cannot be interrupted by a signal. THREAD_INTERRUPTIBLE specifies that the sleep may be interrupted by a "kill -9" signal. THREAD_ABORTSAFE (the default value) specifies that the sleep may be interrupted by any user signal.

Return Value

THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted, 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 function 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, kIOReturnAborted if a disabled command gate is free()ed before being reenabled.

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. If the command is disabled the attempt to run a command will be stalled until enable is called.

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. kIOReturnAborted if a disabled command gate is free()ed before being reenabled, 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. If the command is disabled the attempt to run a command will be stalled until enable is called.

Typedefs

Action

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

ExpansionData

protected

struct ExpansionData {
};
Discussion

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

Member Data

reserved

reserved

protected

ExpansionData *reserved;
Discussion

Reserved for future use. (Internal use only)

 

 

Last Updated: 2009-10-14