IOCommandGate

Inherits from
IOEventSource
Availability
Available in OS X v10.0 and later.
Declared in
IOCommandGate.h

Overview

Single-threaded work-loop client request mechanism.

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.

Tasks

Miscellaneous

Instance Methods

attemptAction

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

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.

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.

commandGate

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

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.

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.

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.

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

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.

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.

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.

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.

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.

Callbacks

Action

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

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

Availability
Declared In
IOCommandGate.h

ExpansionData

struct ExpansionData {
};
Discussion

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

Instance Variables

reserved

ExpansionData *reserved;

Reserved for future use. (Internal use only)