Museum

     TIMEOUT(K)                UNIX System V                TIMEOUT(K)



     Name
          timeout, untimeout - schedules a time to execute a routine

     Syntax
          int
          timeout(routine, arg, clock_ticks)
          int (*routine) ();
          caddr_t arg;
          int clock_ticks;

          void
          untimeout(id)
          int id;

     Description
          timeout schedules a routine to be executed at a specific
          time in the future.  timeout returns an integer
          identification number.  untimeout cancels a timeout request
          using the identfication number returned from timeout.

     Note
          This routine can be used in an interrupt routine only if the
          interrupt priority level does not block the clock interrupt.
          Do not use if the level is at spl6, spl7, splhi, splni or
          spltty.

     Parameters
          timeout has the following arguments:

               routine        a routine to be executed after the
                              specified number of clock_ticks has
                              elapsed.

               arg            passed as a parameter to routine.

               clock_ticks    the number of clock ticks to wait before
                              calling routine.

          The argument to untimeout is the integer identification
          number returned from the timeout call that you wish to
          cancel.

     Notes
          timeout should normally only be used at task time, however
          it can be used in an xxinit routine with this caveat.  Since
          the clock interrupts may not be enabled before your xxinit
          routine is called, the timeout may not elapse when
          specified, but will elapse no later than
          (time_when_clock_started + clock_ticks) times the length of
          one clock tick.

     Example
          timeout(K), sleep(K) and wakeup(K) can be combined to
          provide  a ``busy, wait'' function.  The following code
          sample illustrates this possible functionality:

          #define PERIOD 5         /* 5 clock ticks */
          #define BUSYPRI  (PZERO -1)  /* arbitrary */

          /* Declare routine to use in timeout(). */
          int stopwait();

          /* flag which is used to indicate */
          /* whether to continue waiting.   */
          int status;

          int busywait() /* wait until status is non-zero */
          {
                  while (status == 0) {
                          timeout(stopwait, (caddr_t) &status, PERIOD);
                          sleep(&status, BUSYPRI);
                  }
          }

          int stopwait(arg)
          caddr_t arg;
          {
                  if ( /* what I am waiting for has happened */ )
                          status = 1;
                  else
                          wakeup(arg);
          }

          A device driver should never loop while waiting for a status
          change unless the delay is less than 100 microseconds. Also,
          setting a timeout for fewer than three clock ticks may
          result in the sleep call happening after the timeout has
          occurred. This results in a permanent sleep condition
          (hang).

     See Also
          delay(K), sleep(K), spl(K), wakeup(K)

                                                      (printed 7/7/89)