#include <IOKit/IOCommandGate.h>
IOKit/IOCommandGate.h
[
1999-8-10 Godfrey van der Linden(gvdl)
Created.
]
classIOCommandGate
@class IOCommandGate : public IOEventSource
@abstract 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. Although the code does not
technically execute on the work loop itself, a single-threaded work loop semantic
is maintained for this event source using the work loop gate. 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.
<br><br>
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.
<br><br>
CAUTION: The runAction, runCommand, and attemptCommand functions cannot be called from an interrupt context.
: public IOEventSource
| ExpansionData * | reserved |
static OSPtr<IOCommandGate> commandGate(OSObject *owner, Action action = NULL)static
@function commandGate
@abstract Factory method to create and initialise an IOCommandGate, See $link init.
@result Returns a pointer to the new command gate if sucessful, 0 otherwise.
virtual bool init(OSObject *owner, Action action = NULL)virtual
@function init
@abstract Class initialiser.
@discussion Initialiser for IOCommandGate operates only on newly 'newed'
objects. Shouldn't be used to re-init an existing instance.
@param owner Owner of this, newly created, instance of the IOCommandGate. This argument will be used as the first parameter in the action callout.
@param 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.
@result True if inherited classes initialise successfully.
APPLE_KEXT_OVERRIDE virtual void setWorkLoop(IOWorkLoop *inWorkLoop)virtual
virtual IOReturn runCommand( void *arg0 = NULL, void *arg1 = NULL, void *arg2 = NULL, void *arg3 = NULL )virtual
@function runCommand
@abstract Single thread a command with the target work loop.
@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.
@param arg0 Parameter for action of command gate, defaults to 0.
@param arg1 Parameter for action of command gate, defaults to 0.
@param arg2 Parameter for action of command gate, defaults to 0.
@param arg3 Parameter for action of command gate, defaults to 0.
@result kIOReturnSuccess if successful. kIOReturnAborted if a disabled command gate is free()ed before being reenabled, kIOReturnNoResources if no action available.
virtual IOReturn runAction( Action action, void *arg0 = NULL, void *arg1 = NULL, void *arg2 = NULL, void *arg3 = NULL )virtual
@function runAction
@abstract Single thread a call to an action with the target work loop.
@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.
@param action Pointer to function to be executed in the context of the work loop.
@param arg0 Parameter for action parameter, defaults to 0.
@param arg1 Parameter for action parameter, defaults to 0.
@param arg2 Parameter for action parameter, defaults to 0.
@param arg3 Parameter for action parameter, defaults to 0.
@result The return value of action if it was called, kIOReturnBadArgument if action is not defined, kIOReturnAborted if a disabled command gate is free()ed before being reenabled.
IOReturn runActionBlock(ActionBlock action)
@function runActionBlock
@abstract Single thread a call to an action with the target work loop.
@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.
@param action Block to be executed in the context of the work loop.
@result The return value of action if it was called, kIOReturnBadArgument if action is not defined, kIOReturnAborted if a disabled command gate is free()ed before being reenabled.
virtual IOReturn attemptCommand( void *arg0 = NULL, void *arg1 = NULL, void *arg2 = NULL, void *arg3 = NULL )virtual
@function attemptCommand
@abstract Single thread a command with the target work loop.
@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.
@param arg0 Parameter for action of command gate, defaults to 0.
@param arg1 Parameter for action of command gate, defaults to 0.
@param arg2 Parameter for action of command gate, defaults to 0.
@param arg3 Parameter for action of command gate, defaults to 0.
@result kIOReturnSuccess if successful. kIOReturnNotPermitted if this event source is currently disabled, kIOReturnNoResources if no action available, kIOReturnCannotLock if lock attempt fails.
virtual IOReturn attemptAction( Action action, void *arg0 = NULL, void *arg1 = NULL, void *arg2 = NULL, void *arg3 = NULL )virtual
@function attemptAction
@abstract Single thread a call to an action with the target work loop.
@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.
@param action Pointer to function to be executed in context of the work loop.
@param arg0 Parameter for action parameter, defaults to 0.
@param arg1 Parameter for action parameter, defaults to 0.
@param arg2 Parameter for action parameter, defaults to 0.
@param arg3 Parameter for action parameter, defaults to 0.
@result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNotPermitted if this event source is currently disabled, kIOReturnCannotLock if lock attempt fails.
virtual IOReturn commandSleep(void *event, UInt32 interruptible = THREAD_ABORTSAFE)virtual
@function commandSleep
@abstract Put a thread that is currently holding the command gate to sleep.
@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. If the thread does not hold the gate, panic.
@param event Pointer to an address.
@param 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.
@result THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted, THREAD_RESTART - restart operation entirely.
virtual void commandWakeup(void *event, bool oneThread = false)virtual
@function commandWakeup
@abstract Wakeup one or more threads that are asleep on an event.
@param event Pointer to an address.
@param oneThread true to only wake up at most one thread, false otherwise.
APPLE_KEXT_OVERRIDE
virtual void disable()virtual@function disable
@abstract Disable the command gate
@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.
APPLE_KEXT_OVERRIDE
virtual void enable()virtual@function enable
@abstract Enable command gate, this will unblock any blocked Commands and Actions.
@discussion Enable the command gate. The attemptAction/attemptCommand calls will now be enabled and can succeeed. Stalled runCommand/runAction calls will be woken up.
virtual IOReturn commandSleep(void *event, AbsoluteTime deadline, UInt32 interruptible)virtual
@function commandSleep
@abstract Put a thread that is currently holding the command gate to sleep.
@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. If the thread does not hold the gate, panic.
@param event Pointer to an address.
@param deadline Clock deadline to timeout the sleep.
@param 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.
@result THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted, THREAD_RESTART - restart operation entirely.