itimeout(D3)

NAME
     itimeout, fast_itimeout - 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...);


   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.

     pl        The interrupt priority level at which the function will be
               called.

DESCRIPTION
     These two 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.

     Both 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 specifies the number of tick interrupts to pass before
     the 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.

   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.

REFERENCES
     LOCK_ALLOC(D3), dtimeout(D3), fasthzto(D3), untimeout(D3).