Mac Developer Library

Developer

IOWorkLoop Class Reference

Options
Deployment Target:

On This Page
Language:

IOWorkLoop

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.

An IOWorkLoop is a thread of control that is intended to be used to provide single threaded access to hardware. This class has no knowledge of the nature and type of the events that it marshals and forwards. When a device driver successfully starts (see IOService::start), it is expected to create the event sources it will need to receive events. Then a work loop is initialized and the events are added to the work loop for monitoring. In general this set up will be automated by the family superclass of the specific device.

The thread main method walks the event source linked list and messages each one requesting a work check. At this point each event source is expected to notify its registered owner that the event has occurred. After each event has been walked and each indicates that another loop isn't required (by setting the 'more' flag to false) the thread will go to sleep on a signaling semaphore.

When an event source is registered with a work loop it is informed of the semaphore to use to wake up the loop.

  • Synchronous implementation of addEventSource and removeEventSource functions.

    Declaration

    C++

    virtual IOReturn _maintRequest( void *command, void *data, void *, void *);

    Return Value

    kIOReturnUnsupported if the command given is not implemented, kIOReturnSuccess otherwise.

    Discussion

    This function implements the commands as defined in the maintCommandEnum. It can be subclassed but it isn't an external API in the usual sense. A subclass implementation of _maintRequest would be called synchronously with respect to the work loop and it should be implemented in the usual way that an ioctl would be.

  • Declaration

    C++

    virtual IOReturn addEventSource( IOEventSource *newEvent);

    Parameters

    newEvent

    Pointer to IOEventSource subclass to add.

    Return Value

    Always returns kIOReturnSuccess.

    Discussion

    Add an event source to be monitored by the work loop. This function does not return until the work loop has acknowledged the arrival of the new event source. When a new event has been added the threadMain will always restart its loop and check all outstanding events. The event source is retained by the work loop.

  • Calls disable() in all event sources.

    Declaration

    C++

    virtual void disableAllEventSources() const;

    Discussion

    For all event sources in eventChain, call disable() function. See IOEventSource::disable().

  • Calls disable() in all interrupt event sources.

    Declaration

    C++

    virtual void disableAllInterrupts() const;

    Discussion

    For all event sources (ES) for which OSDynamicCast(IOInterruptEventSource, ES) is valid, in eventChain call disable() function. See IOEventSource::disable().

  • Calls enable() in all event sources.

    Declaration

    C++

    virtual void enableAllEventSources() const;

    Discussion

    For all event sources in eventChain, call enable() function. See IOEventSource::enable().

  • Calls enable() in all interrupt event sources.

    Declaration

    C++

    virtual void enableAllInterrupts() const;

    Discussion

    For all event sources (ES) for which OSDynamicCast(IOInterruptEventSource, ES) is valid, in eventChain call enable() function. See IOEventSource::enable().

  • Checks if the event source passed in overrides checkForWork() to perform any work. IOWorkLoop uses this to determine if the event source should be polled in runEventSources() or not.

    Declaration

    C++

    bool eventSourcePerformsWork( IOEventSource *inEventSource);

    Parameters

    inEventSource

    The event source to check.

  • Declaration

    C++

    virtual void free();

    Discussion

    Mandatory free of the object independent of the current retain count. If the work loop is running, this method will not return until the thread has successfully terminated. Each event source in the chain will be released and the working semaphore will be destroyed.

    If the client has some outstanding requests on an event they will never be informed of completion. If an external thread is blocked on any of the event sources they will be awakened with a KERN_INTERUPTED status.

  • Gets the workThread.

    Declaration

    C++

    virtual IOThread getThread() const;

    Return Value

    Returns workThread.

  • Is the current execution context holding the work-loop's gate?

    Declaration

    C++

    virtual bool inGate() const;

    Return Value

    Returns true if IOThreadSelf() is gate holder.

  • Declaration

    C++

    virtual bool init();

    Return Value

    Returns true if initialized successfully, false otherwise.

    Discussion

    Initializes an instance of the workloop. This method creates and initializes the signaling semaphore, the controller gate lock, and spawns the thread that will continue executing.

  • Is the current execution context on the work thread?

    Declaration

    C++

    virtual bool onThread() const;

    Return Value

    Returns true if IOThreadSelf() == workThread.

  • Declaration

    C++

    virtual IOReturn removeEventSource( IOEventSource *toRemove);

    Parameters

    toRemove

    Pointer to IOEventSource subclass to remove.

    Return Value

    Returns kIOReturnSuccess if successful, kIOReturnBadArgument if toRemove couldn't be found.

    Discussion

    Remove an event source from the work loop. This function does not return until the work loop has acknowledged the removal of the event source. When an event has been removed the threadMain will always restart its loop and check all outstanding events. The event source will be released before return.

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

    Declaration

    C++

    virtual IOReturn runAction( Action action, OSObject *target, 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

    Returns the value of the Action callout.

    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 runAction can cause direct or indirect re-entrancy. When 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.

  • Declaration

    C++

    virtual bool runEventSources();

    Return Value

    Return false if the work loop is shutting down, true otherwise.

    Discussion

    Consists of the inner 2 loops of the threadMain function(qv). The outer loop terminates when there is no more work, and the inside loop walks the event list calling the checkForWork method in each event source. If an event source has more work to do, it can set the more flag and the outer loop will repeat.

    This function can be used to clear a priority inversion between the normal workloop thread and multimedia's real time threads. The problem is that the interrupt action routine is often held off by high priority threads. So if they want to get their data now they will have to call us and ask if any data is available. The multi-media user client will arrange for this function to be called, which causes any pending interrupts to be processed and the completion routines called. By the time the function returns all outstanding work will have been completed at the real time threads priority.

  • Declaration

    C++

    virtual void threadMain();

    Discussion

    Work loop threads main function. This function consists of 3 loops: the outermost loop is the semaphore clear and wait loop, the middle loop terminates when there is no more work, and the inside loop walks the event list calling the checkForWork method in each event source. If an event source has more work to do, it can set the more flag and the middle loop will repeat. When no more work is outstanding the outermost will sleep until an event is signalled.

  • Static function that calls the threadMain function.

    Declaration

    C++

    static void threadMainContinuation( IOWorkLoop *self);

  • Factory member function to construct and intialize a work loop.

    Declaration

    C++

    static IOWorkLoop *workLoop();

    Return Value

    Returns a workLoop instance if constructed successfully, 0 otherwise.

  • Factory member function to constuct and intialize a work loop.

    Declaration

    C++

    static IOWorkLoop *workLoopWithOptions( IOOptionBitsoptions);

    Parameters

    options

    Options - kPreciousStack to avoid stack deallocation on paging path.

    Return Value

    Returns a workLoop instance if constructed successfully, 0 otherwise.

  • Factory member function to constuct and intialize a work loop.

    Declaration

    C++

    static IOWorkLoop *workLoopWithOptions( IOOptionBitsoptions);

    Parameters

    options

    Options - kPreciousStack to avoid stack deallocation on paging path.

    Return Value

    Returns a workLoop instance if constructed successfully, 0 otherwise.

Callbacks

  • Declaration

    C++

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

    Parameters

    target

    Target of the function, can be used as a refcon. Note if a C++ function was specified, this parameter is implicitly the first parameter 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

    CPlusPlus

    typedef enum { mAddEvent, mRemoveEvent } maintCommandEnum;

    Constants

    • mAddEvent

      mAddEvent

      Used to tag a Remove event source command.

    • mRemoveEvent

      mRemoveEvent

      Used to tag a Remove event source command.

    Discussion

    Enumeration of commands that _maintCommand can deal with.

    Import Statement

    Objective-C

    #include <IOWorkLoop.h>;

    Availability

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

  • Declaration

    C++

    struct ExpansionData { IOOptionBits options; IOEventSource *passiveEventChain; #if DEBUG void *allocationBacktrace[16]; #endif /* DEBUG */ #if IOKITSTATS struct IOWorkLoopCounter *counter; #else void *iokitstatsReserved; #endif };

    Discussion

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

Instance Variables

  • The spin lock that is used to guard the 'workToDo' variable.

    Declaration

    C++

    IOSimpleLock *workToDoLock;

  • Used to to indicate that an interrupt has fired and needs to be processed.

    Declaration

    C++

    volatile bool workToDo;

  • Work loop thread.

    Declaration

    C++

    IOThread workThread;

  • Reserved for future use. (Internal use only)

    Declaration

    C++

    ExpansionData *reserved;

  • Set if an event chain has been changed and the system has to be rechecked from start. (Internal use only)

    Declaration

    C++

    bool loopRestart;

  • Mutual exclusion lock that is used by close and open Gate functions. This is a recursive lock, which allows multiple layers of code to share a single IOWorkLoop without deadlock. This is common in IOKit since threads of execution tend to follow the service plane in the IORegistry, and multiple objects along the call path may acquire the gate for the same (shared) workloop.

    Declaration

    C++

    IORecursiveLock *gateLock;

  • Pointer to first event source in linked list.

    Declaration

    C++

    IOEventSource *eventChain;

  • Internal control gate to maintain event system.

    Declaration

    C++

    IOCommandGate *controlG;