ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

IOTimerEventSource

Inherits from:	IOEventSource
Declared In:	IOTimerEventSource.h

Overview

Time based event source mechanism.

Discussion

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.

Functions

cancelTimeout: Disable any outstanding calls to this event source.
checkForWork: Have to implement it is mandatory in IOEventSource, but IOTimerEventSources don't actually use this work-loop mechanism.
disable: Disable a timed callout.
enable: Enables a call to the action.
free: Sub-class implementation of free method, frees calloutEntry
init: Initializes the timer with an owner, and a handler to call when the timeout expires.
setTimeout: Setup a callback at after the delay in decrementer ticks. See wakeAtTime(AbsoluteTime).
setTimeout(mach_timespec_t): Setup a callback at after the delay in decrementer ticks. See wakeAtTime(AbsoluteTime).
setTimeout(UInt32, UInt32): Setup a callback at after the delay in some unit. See wakeAtTime(AbsoluteTime).
setTimeoutFunc: Set's timeout as the function of calloutEntry.
setTimeoutMS: Setup a callback at after the delay in milliseconds. See wakeAtTime(AbsoluteTime).
setTimeoutTicks: Setup a callback at after the delay in scheduler ticks. See wakeAtTime(AbsoluteTime).
setTimeoutUS: Setup a callback at after the delay in microseconds. See wakeAtTime(AbsoluteTime).
timeout: Function that routes the call from the OS' timeout mechanism into a work-loop context.
timerEventSource: Allocates and returns an initialized timer instance.
wakeAtTime: Setup a callback at this absolute time.
wakeAtTime(mach_timespec_t): Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).
wakeAtTime(UInt32, UInt32): Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).
wakeAtTimeMS: Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).
wakeAtTimeTicks: Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).
wakeAtTimeUS: Setup a callback at this absolute time. See wakeAtTime(AbsoluteTime).

cancelTimeout

Disable any outstanding calls to this event source.

public

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.

checkForWork

Have to implement it is mandatory in IOEventSource, but IOTimerEventSources don't actually use this work-loop mechanism.

protected

virtual bool checkForWork();

disable

Disable a timed callout.

public

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.

public

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

protected

virtual void free();

init

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

public

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

Parameters

owner
action

setTimeout

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

public

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(mach_timespec_t)

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

public

virtual IOReturn setTimeout(
    mach_timespec_t interval);

Parameters

interval: Delay from now to wake up.

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).

public

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.

protected

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).

public

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).

public

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).

public

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.

protected

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.

public

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

Parameters

owner
action

wakeAtTime

Setup a callback at this absolute time.

public

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(mach_timespec_t)

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

public

virtual IOReturn wakeAtTime(
    mach_timespec_t abstime);

Parameters

abstime: mach_timespec_t of the desired callout time.

Return Value

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

wakeAtTime(UInt32, UInt32)

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

public

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).

public

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).

public

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).

public

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.

Typedefs

Action

public

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

Fields

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.

Structs and Unions

ExpansionData

protected

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

Discussion

This structure is private to the IOTimerEventSource implementation.

Member Data

abstime

protected

AbsoluteTime abstime;

Discussion

time to wake up next, see enable.

calloutEntry

protected

void *calloutEntry;

Discussion

thread_call entry for preregistered thread callouts

reserved

protected

ExpansionData *reserved;

Discussion

Reserved for future use. (Internal use only)

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-12-19