itimeout(D3)itimeout(D3)NAME
itimeout, fast_itimeout, clock_prtimeout - execute a function after a
(possibly high resolution) delay
SYNOPSIS
#include <sys/types.h>
#include <sys/ddi.h>
toid_t itimeout(void (*func)(), void *arg, long ticks,
pl_t pl, void *arg2...);
toid_t fast_itimeout(void (*func)(), void *arg, long fast_ticks,
pl_t pl, void *arg2...);
toid_t clock_prtimeout(processorid_t cpu, void (*func)(),
void *arg, __int64_t tim, short pri,
void *arg2...)
Arguments
func Function to execute when the time increment expires.
arg First or only argument to the function.
arg2... Optional, additional arguments to the function.
ticks Number of (fast or normal) clock ticks to wait before the
function is called.
tim Value of the Real-Time Clock (RTC) when the function will be
called.
pl The interrupt priority level at which the function will be
called.
pri The cpu scheduling priority level at which the function will be
called.
DESCRIPTION
These three functions are nearly identical, the difference being which
clock is used. itimeout schedules the function specified by func to be
called after the time interval specified by ticks, while fast_itimeout
schedules the function specified by func to be called after the the
number of fast clock ticks specified by fast_ticks. The resolution of
the fast clock varies with system type, and with local setup, because it
is a tuneable value. It is typically near one millisecond. See the
function fasthzto(D3) for a standard way to convert from a timeval to
fast ticks.
clock_prtimeout schedules the function specified by func to be called at
the time specified by tim. This function is only available on SGI
Origin, Octane, and Challenge series systems. These systems have an RTC
Page 1
itimeout(D3)itimeout(D3)
that monotonically increases from boot time and that can be read with
rtc_read(D3). The resolution of a system's RTC can be acquired from
rtc_resolution(D3) and can be expected to be at least 800ns per tick.
Unlike the other two functions, clock_prtimeout takes its time argument
as an absolute time and not as a delta from the current time.
The first two functions call the function at the interrupt priority level
specified by pl. The first argument to func is arg. If additional
arguments are passed following pl (varargs), they also are are passed to
func.
The call returns immediately without waiting for the specified function
to execute.
Return Values
If the function specified by func is successfully scheduled, itimeout
returns a non-zero value that can be passed to untimeout to cancel the
request. If the function could not be scheduled, itimeout returns a
value of 0.
USAGE
pl must specify a priority level greater than or equal to pltimeout.
Identifiers for priority levels are declared in sys/ddi.h; plhi is the
typical value to pass.
Note that no matter what value is given for pl, other CPUs can be
executing kernel code concurrently with the execution of func, including
other instances of the same driver that scheduled func and even other
instances of func itself. Hence it is essential to use locking to protect
critical data.
The ticks argument for the first two functions specifies the number of
tick interrupts to pass before the indicated function is called. A ticks
value of 0 is treated as if it were 1. After the specified number of
ticks have been counted, the call to func is deferred until the processor
is at base level.
The length of time before the function is called is not guaranteed to be
exactly equal to the requested time, but will be at least ticks-1 clock
ticks in length.
When called, func may not lower the priority level below pl.
If itimeout is called holding a lock that is claimed by func, the caller
must hold the lock at a processor level greater than the base processor
level.
Loadable drivers must use untimeout() to cancel any pending timeout
functions before unloading; otherwise a kernel panic can result when the
no-longer-loaded function is called. A driver that is deallocating a
data structure must be careful to cancel any pending timeout function
that refers to the data structure.
Page 2
itimeout(D3)itimeout(D3)
Level
Base or Interrupt.
Synchronization Constraints
Driver-defined basic locks, read/write locks, and sleep locks may be held
across calls to this function.
Examples
See copyb(D3) for an example of itimeout.
REFERENCESLOCK_ALLOC(D3), dtimeout(D3), fasthzto(D3), rtc_read(D3),
rtc_resolution(D3), untimeout(D3).
Page 3