IOTimerEventSource

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

Overview

Time based event source mechanism.

An event source that implements a simple timer. A timeout handler is called once the timeout period expires. This timeout handler will be called by the work-loop that this event source is attached to.

Usually a timer event source will be used to implement a timeout. In general when a driver makes a request it will need to setup a call to keep track of when the I/O doesn't complete. This class is designed to make that somewhat easier.

Remember the system doesn't guarantee the accuracy of the callout. It is possible that a higher priority thread is running which will delay the execution of the action routine. In fact the thread will be made runable at the exact requested time, within the accuracy of the CPU's decrementer based interrupt, but the scheduler will then control execution.

Tasks

Miscellaneous

Instance Methods

cancelTimeout

Disable any outstanding calls to this event source.

virtual void cancelTimeout();
Discussion

Clear down any oustanding calls. By the time this function completes it is guaranteed that the action will not be called again.

disable

Disable a timed callout.

virtual void disable();
Discussion

When disable returns the action will not be called until the next time enable(qv) is called.

enable

Enables a call to the action.

virtual void enable();
Discussion

Allows the action function to be called. If the timer event source was disabled while a call was outstanding and the call wasn't cancelled then it will be rescheduled. So a disable/enable pair will disable calls from this event source.

free

Sub-class implementation of free method, frees calloutEntry

virtual void free();

init

Initializes the timer with an owner, and a handler to call when the timeout expires.

virtual bool init( OSObject *owner, Action action = 0);
Parameters
owner
action

setTimeout(AbsoluteTime)

Setup a callback at after the delay in decrementer ticks. See wakeAtTime(AbsoluteTime).

virtual IOReturn setTimeout( AbsoluteTime interval);
Parameters
interval

Delay from now to wake up in decrementer ticks.

Return Value

kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared.

setTimeout(UInt32, UInt32)

Setup a callback at after the delay in some unit. See wakeAtTime(AbsoluteTime).

virtual IOReturn setTimeout( UInt32 interval, UInt32 scale_factor = kNanosecondScale);
Parameters
interval

Delay from now to wake up in some defined unit.

scale_factor

Define the unit of interval, default to nanoseconds.

Return Value

kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared.

setTimeoutFunc

Set's timeout as the function of calloutEntry.

virtual void setTimeoutFunc();
Discussion

IOTimerEventSource is based upon the kern/thread_call.h APIs currently. This function allocates the calloutEntry member variable by using thread_call_allocate(timeout, this). If you need to write your own subclass of IOTimerEventSource you probably should override this method to allocate an entry that points to your own timeout routine.

setTimeoutMS

Setup a callback at after the delay in milliseconds. See wakeAtTime(AbsoluteTime).

virtual IOReturn setTimeoutMS( UInt32 ms);
Parameters
interval

Delay from now to wake up, time in milliseconds.

Return Value

kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared.

setTimeoutTicks

Setup a callback at after the delay in scheduler ticks. See wakeAtTime(AbsoluteTime).

virtual IOReturn setTimeoutTicks( UInt32 ticks);
Parameters
interval

Delay from now to wake up, in scheduler ticks, whatever that may be.

Return Value

kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared.

setTimeoutUS

Setup a callback at after the delay in microseconds. See wakeAtTime(AbsoluteTime).

virtual IOReturn setTimeoutUS( UInt32 us);
Parameters
interval

Delay from now to wake up, time in microseconds.

Return Value

kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared.

timeout

Function that routes the call from the OS' timeout mechanism into a work-loop context.

static void timeout( void *self);
Parameters
self

This argument will be cast to an IOTimerEventSource.

Discussion

timeout will normally not be called nor overridden by a subclass. If the event source is enabled then close the work-loop's gate and call the action routine.

timerEventSource

Allocates and returns an initialized timer instance.

static IOTimerEventSource * timerEventSource( OSObject *owner, Action action = 0);
Parameters
owner
action

wakeAtTime(AbsoluteTime)

Setup a callback at this absolute time.

virtual IOReturn wakeAtTime( AbsoluteTime abstime);
Parameters
abstime

Absolute Time when to wake up, counted in 'decrementer' units and starts at zero when system boots.

Return Value

kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared by init or IOEventSource::setAction (qqv).

Discussion

Starts the timer, which will expire at abstime. After it expires, the timer will call the 'action' registered in the init() function. This timer is not periodic, a further call is needed to reset and restart the timer after it expires.

wakeAtTime(UInt32, UInt32)

Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).

virtual IOReturn wakeAtTime( UInt32 abstime, UInt32 scale_factor = kNanosecondScale);
Parameters
abstime

Time to wake up in some unit.

scale_factor

Define the unit of abstime, default to nanoseconds.

Return Value

kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared.

wakeAtTimeMS

Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).

virtual IOReturn wakeAtTimeMS( UInt32 ms);
Parameters
abstime

Time to wake up in milliseconds.

Return Value

kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared.

wakeAtTimeTicks

Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).

virtual IOReturn wakeAtTimeTicks( UInt32 ticks);
Parameters
abstime

Time to wake up in scheduler quantums, whatever that is?

Return Value

kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared.

wakeAtTimeUS

Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).

virtual IOReturn wakeAtTimeUS( UInt32 us);
Parameters
abstime

Time to wake up in microseconds.

Return Value

kIOReturnSuccess if everything is fine, kIOReturnNoResources if action hasn't been declared.

Callbacks

Action

typedef void ( *Action)(
   OSObject *owner,
   IOTimerEventSource *sender);

Parameters
owner

Owning target object. Note by a startling coincidence the first parameter in a C callout is currently used to define the target of a C++ member function.

sender

The object that timed out.

Discussion

'C' Function pointer defining the callout routine of this event source.

Availability
Declared In
IOCommandGate.h

ExpansionData

struct ExpansionData {
   SInt32 calloutGeneration;
   IOWorkLoop *workLoop;
};
Discussion

This structure is private to the IOTimerEventSource implementation.

Instance Variables

abstime

AbsoluteTime abstime;

time to wake up next, see enable.

calloutEntry

void *calloutEntry;

thread_call entry for preregistered thread callouts

reserved

ExpansionData *reserved;

Reserved for future use. (Internal use only)