untimeout(9F)

NAME

untimeout − cancel previous timeout function call

SYNOPSIS

#include <sys/types.h>
int untimeout(int id);

ARGUMENTS

id Identification value generated by a previous timeout(9F) function call.

INTERFACE LEVEL

Architecture independent level 1 (DDI/DKI).

DESCRIPTION

untimeout() cancels a pending timeout(9F) request.

untimeout() will not return until the pending callback is cancelled or has run. Because of this, locks acquired by the callback routine should not be held across the call to untimeout() or a deadlock may result.

RETURN VALUES

untimeout() returns -1 if the id is not found.

CONTEXT

untimeout() can be called from user or interrupt context.

EXAMPLE

A driver may have to repeatedly request outside help from a computer operator. timeout() is used to delay a certain amount of time between requests. However, once the request is honored, the driver will want to cancel the timeout() operation. This is done with untimeout().

In a driver open(9E) routine, after the input arguments have been verified, the status of the device is tested. If the device is not on-line, a message is displayed on the system console. The driver schedules a cv_signal(9F) call and waits for five minutes (line 48). If the device is still not ready, the procedure is repeated.

When the device is made ready, an interrupt is generated. The driver interrupt handling routine notes there is a suspended process. It cancels the timeout() request (line 68), and signals the suspended process (line 70).

1 struct mtu_device {
2                             /∗ layout of physical device registers ∗/
3          int      control; /∗ physical device control word        ∗/
4          int      status;   /∗ physical device status word         ∗/
5          int      byte_cnt; /∗ number of bytes to be transferred   ∗/
6          paddr_t baddr:    /∗ DMA starting physical address       ∗/
7 };
8
9 struct mtu     {
10                             /∗ magnetic tape unit logical structure ∗/
11         struct buf ∗mtu_head; /∗ pointer to I/O queue head         ∗/
12         struct buf ∗mtu_tail; /∗ pointer to buffer I/O queue tail ∗/
13         int        mtu_flag;   /∗ logical status flag               ∗/
14         int        mtu_to_id; /∗ time out ID number                ∗/
15                             /∗ pointer to device registers ∗/
16         volatile struct mtu_device ∗mtu_regp;
17         kmutex_t   mtu_mutex; /∗ mutex to protect structure ∗/
18         kcondvar_t mtu_cv;     /∗ condition variable to wait on for ∗/
19                                /∗ timeout ∗/
             ...
20 };
21
22 static void ∗mtu_statep;    /∗ for soft_state routines ∗/
      ...
23 mtu_open(dev_t ∗devp, int flag, int otyp, cred_t ∗credp)
24 {
25      struct mtu ∗dp;
26      volatile struct mtu_device ∗rp;
27      int instance;
28
29      instance = getminor(∗devp);
30      dp = ddi_get_soft_state(statep, instance);
31      if (dp == NULL) {              /∗ if dev doesn’t exist ∗/
32          return(ENXIO);             /∗ then return error condition ∗/
33      }
34
35      mutex_enter(&dp->mtu_mutex);
36      if (dp->mtu_flag & MTU_BUSY) != 0) { /∗ if device is in use, ∗/
37          mutex_exit(&dp->mtu_mutex);
38          return(EBUSY);                       /∗ return busy status ∗/
39      }
40
41      dp->mtu_flag = MTU_BUSY;   /∗ mark device in use & clear flags ∗/
42      rp = dp->mtu_regp;         /∗ get device regs ∗/
43      while((rp->status & MTU_LOAD) == 0) { /∗ while tape not loaded ∗/
44                                 /∗ display mount request on console ∗/
45          cmn_err(CE_NOTE, "!Tape MOUNT, mtu%d",
46              getminor(∗devp));
47          dp->mtu_flag |= MTU_WAIT;   /∗ indicate process suspended ∗/
48          dp->mtu_to_id = timeout(cv_signal, (caddr_t)&dp->mtu_cv,
49              5∗60∗drv_usectohz(1000000)); /∗ wait 5 min ∗/
50          /∗wait on tape load ∗/
51          if (cv_wait_sig(&dp->mtu_cv, &dp->mtu_mutex)) == 0){
52                                  /∗ if user aborts process, release ∗/
53              dp->mtu_flag = 0;   /∗ tape device by clearing flags ∗/
54              (void)untimeout(dp->mtu_to_id);
55              mutex_exit(&dp->mtu_mutex);
56              return EINTR;
57           }
58      }
59      mutex_exit(&dp->mtu_mutex);
60      return 0;
61 }
       ...
62 mtu_intr(caddr_t arg)
63 {
64      struct mtu ∗dp = (struct mtu ∗)arg; /∗ from ddi_add_intr ∗/
65      volatile struct mtu_device ∗rp = dp->mtu_regs; /∗ get device regs ∗/
       ...
66      if ((dp->mtu_flag & MTU_WAIT) != 0){ /∗ if process is suspended ∗/
67                                           /∗ waiting for tape mount, ∗/
68          (void)untimeout(dp->mtu_to_id); /∗ cancel timeout request ∗/
69          dp->flag &= ~MTU_WAIT;           /∗ clear wait flag ∗/
70          cv_signal(&dp->mtu_cv);          /∗ signal suspended process ∗/
71      }
       ...
72 }

Museum

Related Articles