SVR5

itimeout(D3)

itimeout -- execute a function after a specified length of time

Synopsis

   #include <sys/types.h>
   #include <sys/ddi.h>
   
   toid_t itimeout(void (*fn)(), void *arg, long ticks, pl_t pl);

Description

itimeout causes the function specified by fn to be called after the time interval specified by ticks, at the interrupt priority level specified by pl. arg will be passed as the only argument to function fn. The itimeout call returns immediately without waiting for the specified function to execute.

Arguments

fn

Function to execute when the time increment expires. The function specified by fn runs in interrupt context in HDK Technical Reference and must not lower the interrupt priority below that specified by the pl argument." fn will be run at some point after the time interval expires. Like a device interrupt (see intr(D2)), it may need to be deferred until the interrupt priority is dropped to a sufficiently low level. Timer callback functions are only run when the interrupt priority level is plbase; they never interrupt device interrupt handlers.

arg

Argument to the function.

ticks

Number of clock ticks to wait before the function is called. 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.

A ticks argument of 0 has the same effect as a ticks argument of 1. Both will result in an approximate wait of between 0 and 1 tick (possibly longer).

The flag TO_PERIODIC can be logically OR'ed into the ticks argument to indicate a repeating periodic timer. When this is used, the specified function will be called every ticks clock ticks, instead of just once; successive calls will compensate for any delay in a previous cycle, so that there is no cumulative drift. The repeating timer can be canceled by untimeout(D3), just like any other timeout.

pl

The interrupt priority level at which the function will be called. pl must specify a priority level greater than or equal to ``pltimeout''; thus, ``plbase'' cannot be used. See pl(D5) for a list of values for pl.

Return values

If the function specified by func is successfully scheduled, itimeout( ) returns a non-zero identifier that can be passed to the untimeout( ) function to cancel the request. If the function could not be scheduled, itimeout( ) returns a value of 0.

Usage

If itimeout is called holding a lock that is contended for by fn, the caller must hold the lock at a processor level greater than the base processor level.

Drivers should be careful to cancel any pending itimeout( ) functions that access data structures before these structures are de-initialized or deallocated.

Context and synchronization

Non-blockable, user or blockable context.

Examples

See copyb(D3str) for an example of itimeout.

Hardware applicability

All

Version applicability

ddi: 3, 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8, 8mp

Differences between versions

Starting with DDI version 7, itimeout( ) replaces timeout(D3). itimeout( ) returns an error instaed of causing a panic when no more space is available, so drivers can handle the error, which improves system reliability and availability. itimeout( ) also allows the driver to select an interrupt priority other than plhi.

References

dtimeout(D3), pl(D5), untimeout(D3)

``Timeouts'' in HDK Technical Reference