.if n .pH ddi.rm/d3/386/dtimeout @(#)dtimeout	43.8 of 11/27/92
.\" Copyright 1991, 1992 UNIX System Laboratories, Inc.
.\" Copyright 1989, 1990  AT&T
.TH dtimeout D3
.IX "\f4dtimeout\fP(D3)"
.SH NAME
\f4dtimeout\fP \- execute a function on a specified processor after a specified length of time
.SH SYNOPSIS
.nf
.na
.ft 4
#include <sys/types.h>
#include <sys/ddi.h>
.sp 0.4
toid_t dtimeout(void (*\f2fn\fP)(), void *\f2arg\fP, long \f2ticks\fP, pl_t \f2pl\fP,
	processorid_t \f2processor\fP, \f2arg2\fP, \f2arg3\fP, \f2arg4\fP);
.ft 1
.ad
.fi
.SS Arguments
.RS 0
.IP "\f2fn\fP" 12n
Function to execute on the specified processor when the time increment
expires.
.IP "\f2arg, arg2, arg3, arg4\fP" 12n
Argument to the function.
.IP "\f2ticks\fP" 12n
Number of clock ticks to wait before the function is called.
.IP "\f2pl\fP" 12n
The interrupt priority level at which the function will be called.
.IP "\f2processor\fP" 12n
Processor on which the function must execute.
.RE
.SH DESCRIPTION
\f4dtimeout\fP causes the function specified by \f2fn\fP to be
called after the time interval specified by \f2ticks\fP,
on the processor specified by \f2processor\fP,
at the interrupt priority level specified by \f2pl\fP.
\f2arg\fP will be passed as the only argument to function \f2fn\fP.
The \f4dtimeout\fP call returns immediately without waiting for the specified
function to execute.
.SS "Return Values"
If the function specified by \f2fn\fP is successfully scheduled, \f4dtimeout\fP
returns a non-zero identifier that can be passed to \f4untimeout\fP to cancel
the request.
If the function could not be scheduled on the specified processor, \f4dtimeout\fP
returns a value of 0.
.SH USAGE
This directed timeout capability provides a form of dynamic processor binding
for driver code.
.P
Drivers should be careful to cancel any pending \f4dtimeout\fP functions
that access data structures
before these structures are de-initialized or deallocated.
.SS "fn Argument"
The function specified by \f2fn\fP must not
lower the priority level below \f2pl\fP.
.P
After the time interval has expired, \f2fn\fP only runs if the processor is
at base level.
Otherwise, \f2fn\fP is deferred until some time in the near future.
.P
If \f4dtimeout\fP is called holding a lock
that is contended for by \f2fn\fP,
the caller must hold the lock at a processor level
greater than the base processor level.
.SS "ticks Argument"
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 \f2ticks\-1\fP
clock ticks in length.
.P
A \f2ticks\fP argument of 0 has the same effect as a \f2ticks\fP argument of 1.
Both will result in an approximate wait of between 0 and 1 tick
(possibly longer).
.SS "pl Argument"
\f2pl\fP must specify a priority level
greater than or equal to \f2pltimeout\fP;
thus, \f2plbase\fP cannot be used.
See \f4LOCK_ALLOC\fP(D3) for a list of values for \f2pl\fP. 
Your driver should treat pl as an "opaque" and should not
try to compare or do any operation
.SS Level  
Base or Interrupt.
.SS "Synchronization Constraints"
Driver-defined basic locks, read/write locks, and sleep locks
may be held across calls to this function.
.SH REFERENCES
.na
\f4itimeout\fP(D3),
\f4LOCK_ALLOC\fP(D3),
\f4untimeout\fP(D3)
.ad