dtimeout(D3DK) —

.IX \f4dtimeout\fP(D3DK)

NAME

dtimeout − execute a function on a specified processor, after a specified length of time

SYNOPSIS

#include <sys/types.h>
toid_t dtimeout(void (∗fn)(), void ∗arg, long ticks, pl_t pl,
processorid_t processor);

ARGUMENTS

fnFunction to execute on the specified processor when the time increment expires.

argArgument to the function.

ticksNumber of clock ticks to wait before the function is called.

plThe 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 LOCK_ALLOC(D3DK) for a list of values for pl.

processorProcessor on which the function must execute.

DESCRIPTION

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

This directed timeout capability provides a form of dynamic processor binding for driver code.

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. The function specified by fn must neither sleep nor reference process context.

RETURN VALUE

If the function specified by fn is successfully scheduled, dtimeout returns a non-zero identifier that can be passed to untimeout to cancel the request. If the function could not be scheduled on the specified processor, dtimeout returns a value of 0.

LEVEL

Base or Interrupt.

NOTES

Does not sleep. Driver defined basic locks, read/write locks, and sleep locks may be held across calls to this function. Drivers should be careful to cancel any pending dtimeout functions that access data structures before these structures are de-initialized or deallocated. After the time interval has expired, fn only runs if the processor is at base level. Otherwise, fn is deferred until some time in the near future. If dtimeout is called holding a lock that is contended for by fn, the caller must hold the lock at an interrupt level greater than the base interrupt level. 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).

Museum