#include <IOKit/IOWorkLoop.h>
Kernel (KEXT) › IOKit

IOKit/IOWorkLoop.h Kernel.framework

includes: libkern/c++/OSObject.h, IOKit/IOReturn.h, IOKit/IOLib.h, IOKit/IOLocks.h, libkern/c++/OSPtr.h, IOKit/system.h
1 class

classIOWorkLoop

@class IOWorkLoop @discussion 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. <br><br> 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. <br><br> When an event source is registered with a work loop it is informed of the semaphore to use to wake up the loop.
: public OSObject
IORecursiveLock *gateLock
IOEventSource *eventChain
IOCommandGate *controlG
IOSimpleLock *workToDoLock
IOThreadworkThread
volatile boolworkToDo
boolloopRestart
ExpansionData *reserved
virtual IOReturn _maintRequest(void *command, void *data, void *, void *)virtual protected
@function _maintRequest @abstract Synchronous implementation of addEventSource and removeEventSource functions. @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. @return kIOReturnUnsupported if the command given is not implemented, kIOReturnSuccess otherwise.
APPLE_KEXT_OVERRIDE
virtual void free()
virtual protected
@function 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. <br><br> 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.
virtual void threadMain()virtual protected
@function 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 OSPtr<IOWorkLoop> workLoop()static
@function workLoop @abstract Factory member function to construct and intialize a work loop. @result Returns a workLoop instance if constructed successfully, 0 otherwise.
static OSPtr<IOWorkLoop> workLoopWithOptions(IOOptionBits options)static
@function workLoopWithOptions(IOOptionBits options) @abstract Factory member function to constuct and intialize a work loop. @param options Options - kPreciousStack to avoid stack deallocation on paging path. @result Returns a workLoop instance if constructed successfully, 0 otherwise.
APPLE_KEXT_OVERRIDE
virtual bool init()
virtual
@function init @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. @result Returns true if initialized successfully, false otherwise.
virtual IOThread getThread() constvirtual
@function getThread @abstract Gets the workThread. @result Returns workThread.
virtual bool onThread() constvirtual
@function onThread @abstract Is the current execution context on the work thread? @result Returns true if IOThreadSelf() == workThread.
virtual bool inGate() constvirtual
@function inGate @abstract Is the current execution context holding the work-loop's gate? @result Returns true if IOThreadSelf() is gate holder.
virtual IOReturn addEventSource(IOEventSource *newEvent)virtual
@function addEventSource @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. @param newEvent Pointer to IOEventSource subclass to add. @result Always returns kIOReturnSuccess.
virtual IOReturn removeEventSource(IOEventSource *toRemove)virtual
@function removeEventSource @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. @param toRemove Pointer to IOEventSource subclass to remove. @result Returns kIOReturnSuccess if successful, kIOReturnBadArgument if toRemove couldn't be found.
virtual void enableAllEventSources() constvirtual
@function enableAllEventSources @abstract Calls enable() in all event sources. @discussion For all event sources in eventChain, call enable() function. See IOEventSource::enable().
virtual void disableAllEventSources() constvirtual
@function disableAllEventSources @abstract Calls disable() in all event sources. @discussion For all event sources in eventChain, call disable() function. See IOEventSource::disable().
virtual void enableAllInterrupts() constvirtual
@function enableAllInterrupts @abstract Calls enable() in all interrupt event sources. @discussion For all event sources (ES) for which OSDynamicCast(IOInterruptEventSource, ES) is valid, in eventChain call enable() function. See IOEventSource::enable().
virtual void disableAllInterrupts() constvirtual
@function disableAllInterrupts @abstract Calls disable() in all interrupt event sources. @discussion For all event sources (ES) for which OSDynamicCast(IOInterruptEventSource, ES) is valid, in eventChain call disable() function. See IOEventSource::disable().
virtual void signalWorkAvailable()virtual protected
virtual void openGate()virtual protected
virtual void closeGate()virtual protected
virtual bool tryCloseGate()virtual protected
virtual int sleepGate(void *event, UInt32 interuptibleType)virtual protected
virtual void wakeupGate(void *event, bool oneThread)virtual protected
virtual IOReturn runAction(
	Action action,
	OSObject *target,
	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 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 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. @param action Pointer to function to be executed in work-loop context. @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 Returns the value of the Action callout.
IOReturn runActionBlock(ActionBlock action)
@function runAction @abstract Single thread a call to an action with the 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 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. @param action Block to be executed in work-loop context. @result Returns the result of the action block.
virtual bool runEventSources()virtual
@function runEventSources @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. <br><br> 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. @result Return false if the work loop is shutting down, true otherwise.
void setMaximumLockTime(uint64_t interval, uint32_t options)
@function setMaximumLockTime @discussion For diagnostics use in DEVELOPMENT kernels, set a time interval which if the work loop lock is held for this time or greater, IOWorkLoop will panic or log a backtrace. @param interval An absolute time interval, eg. created with clock_interval_to_absolutetime_interval(). @param options Pass IOWorkLoop::kTimeLockPanics to panic when the time is exceeded, otherwise a log will be generated with OSReportWithBacktrace().
virtual int sleepGate(void *event, AbsoluteTime deadline, UInt32 interuptibleType)virtual protected
Internal APIs used by event sources to control the thread