Mac Developer Library

Developer

IOCommandGate Class Reference

Options
Deployment Target:

On This Page
Language:

IOCommandGate

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.

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.
  • Single thread a call to an action with the target work-loop.

    Declaration

    C++

    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.

  • Single thread a command with the target work-loop.

    Declaration

    C++

    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.

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

    Declaration

    C++

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

    Return Value

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

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

    Declaration

    C++

    virtual IOReturn commandSleep( void *event, AbsoluteTimedeadline, UInt32interruptible);

    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.

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

    Declaration

    C++

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

    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.

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

    Declaration

    C++

    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 the command gate

    Declaration

    C++

    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 command gate, this will unblock any blocked Commands and Actions.

    Declaration

    C++

    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.

  • Class initialiser.

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

  • Single thread a command with the target work-loop.

    Declaration

    C++

    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

  • Declaration

    C++

    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.

    Import Statement

    Objective-C

    #include <IOCommandGate.h>;

    Availability

    Available in OS X v10.0 through OS X v10.5.

Data Types

  • Declaration

    C++

    struct ExpansionData { };

    Discussion

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

Instance Variables

  • Reserved for future use. (Internal use only)

    Declaration

    C++

    ExpansionData *reserved;