illumos: manual page: qtimeout.9f

QTIMEOUT(9F) Kernel Functions for Drivers QTIMEOUT(9F)

NAME

qtimeout - execute a function after a specified length of time

SYNOPSIS

#include <sys/stream.h>
#include <sys/ddi.h>

timeout_id_t qtimeout(queue_t *q, void (*func)(void *),
void *arg, clock_t ticks);

INTERFACE LEVEL

illumos DDI specific (illumos DDI).

PARAMETERS

q
Pointer to STREAMS queue structure.

func
Kernel function to invoke when the time increment expires.

arg
Argument to the function.

ticks
Number of clock ticks to wait before the function is called. Use
drv_usectohz(9F) to convert microseconds to clock ticks.

DESCRIPTION

The qtimeout() function schedules the specified function func to be
called after a specified time interval. func is called with arg as a
parameter. Control is immediately returned to the caller. This is useful
when an event is known to occur within a specific time frame, or when you
want to wait for I/O processes when an interrupt is not available or
might cause problems. The exact time interval over which the timeout
takes effect cannot be guaranteed, but the value given is a close
approximation.

The qtimeout() function is tailored to be used with the enhanced STREAMS
framework interface which is based on the concept of perimeters. (See
mt-streams(9F).) qtimeout() schedules the specified function to execute
after entering the perimeters associated with the queue passed in as the
first parameter to qtimeout(). All outstanding timeouts and bufcalls must
be cancelled (using, respectively, quntimeout(9F) and qunbufcall(9F))
before a driver close routine can block and before the close routine
calls qprocsoff(9F).

The qprocson(9F) function must be called before calling qtimeout().

RETURN VALUES

The qtimeout() function returns an opaque non-zero timeout identifier
that can be passed to quntimeout(9F) to cancel the request. Note: No
value is returned from the called function.

CONTEXT

The qtimeout() function can be called from user, interrupt, or kernel
context.