'\" te
.\"  Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
.TH ddi_periodic_delete 9F "6 May 2009" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
ddi_periodic_delete \- cancel nanosecond periodic timeout requests
.SH SYNOPSIS
.LP
.nf
#include <sys/dditypes.h> 
#include <sys/sunddi.h>

\fBvoid\fR \fBddi_periodic_delete\fR(\fBddi_periodic_t\fR \fIreq\fR\fB);\fR
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIreq\fR\fR
.ad
.RS 7n
.rt  
\fBddi_periodic_t\fR opaque value returned by \fBddi_periodic_add\fR(9F)
.RE

.SH DESCRIPTION
.sp
.LP
The \fBddi_periodic_delete()\fR function cancels the \fBddi_periodic_add\fR(9F) request that was previously issued.
.sp
.LP
As with \fBuntimeout\fR(9F), calling \fBddi_periodic_delete()\fR against a periodic \fItimeout\fR request which is either running on another CPU, or has already been canceled causes no problems. Unlike \fBuntimeout\fR(9F), there are no restrictions on the lock which might be held across the call to \fBddi_periodic_delete()\fR.
.SH CONTEXT
.sp
.LP
The \fBddi_periodic_delete()\fR function may be called from user or kernel context.
.SH EXAMPLES
.LP
\fBExample 1 \fRCancelling a timeout request
.sp
.LP
In the following example, the device driver cancels the \fItimeout\fR request by calling \fBddi_periodic_delete()\fR against the request that was previously issued.

.sp
.in +2
.nf
/*
* Stop the periodic timer
*/
static void
stop_periodic_timer(struct my_state *statep)
{
         ddi_periodic_delete(statep->periodic_id);
         delay(1); /* wait for one tick */
         mutex_destory(&statep->lock);
}

static void
start_periodic_timer(struct my_state *statep)
{
         hrtime_t interval = CHECK_INTERVAL;

         mutex_init(&statep->lock, NULL, MUTEX_DRIVER,
             (void *)DDI_IPL_0);

         /*
          * Register my_callback which is invoked periodically
          * in CHECK_INTERVAL in kernel context.
          */
         statep->periodic_id = ddi_periodic_add(my_periodic_func,
             statep, interval, DDI_IPL_0);
}

static void
my_periodic_func(void *arg)
{
           /*
            * This handler is invoked periodically.
            */
           struct my_state *statep = (struct my_state *)arg;

           mutex_enter(&statep->lock);
           if (load_unbalanced(statep)) {
               balance_tasks(statep);
           }
           mutex_exit(&statep->lock);
}
.fi
.in -2

.SH SEE ALSO
.sp
.LP
\fBcv_timedwait\fR(9F), \fBddi_intr_get_pri\fR(9F), \fBddi_periodic_add\fR(9F), \fBdelay\fR(9F), \fBdrv_usectohz\fR(9F), \fBqtimeout\fR(9F), \fBquntimeout\fR(9F), \fBtimeout\fR(9F), \fBuntimeout\fR(9F)
.SH NOTES
.sp
.LP
There might be a race between a callback invocation and \fBddi_periodic_delete()\fR. A device driver should take a responsibility for this avoidance if needed by using the kernel synchronization such as a mutex lock or calling \fBdelay\fR(9F) as in the example above.