share/man/man9/systimer.9

   1 .\"
   2 .\" Copyright (c) 2010, The DragonFly Project.
   3 .\"
   4 .\" This software is derived from software contributed to the DragonFly Project
   5 .\" by Venkatesh Srinivas <me@endeavour.zapto.org>.
   6 .\"
   7 .\" Permission to use, copy, modify, or distribute this software for any
   8 .\" purpose with or without fee is hereby granted, provided that the above
   9 .\" copyright notice and this permission notice appear in all copies.
  10 .\"
  11 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  12 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  13 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  14 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR OTHER DAMAGES
  15 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA, OR PROFITS, WHETHER IN AN
  16 .\" ACTION OF CONTRACT, NEGLIGENCE, OR OTHER TORTIOUS ACTION, ARISING OUT OF
  17 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  18 .\"
  19 .Dd August 19, 2010
  20 .Os
  21 .Dt SYSTIMER 9
  22 .Sh NAME
  23 .Nm systimer_init_periodic ,
  24 .Nm systimer_init_periodic_nq ,
  25 .Nm systimer_adjust_periodic ,
  26 .Nm systimer_init_oneshot
  27 .Nd periodic callbacks
  28 .Sh SYNOPSIS
  29 .In sys/systimer.h
  30 .Ft void
  31 .Fn systimer_init_periodic "systimer_t info" "void *func" "void *data" "int hz"
  32 .Ft void
  33 .Fn systimer_init_periodic_nq "systimer_t info" "void *func" "void *data" "int hz"
  34 .Ft void
  35 .Fn systimer_adjust_periodic "systimer_t info" "int hz"
  36 .Ft void
  37 .Fn systimer_init_oneshot "systimer_t info" "void *func" "void *data" "int us"
  38 .Sh DESCRIPTION
  39 .Pp
  40 Systimers invoke callbacks at either fixed frequencies or after time delays. The
  41 callbacks are invoked in an interrupt thread and should only be used for limited
  42 work.
  43 .Pp
  44 The
  45 .Fn systimer_init_periodic
  46 function initializes a systimer callback function to be called at frequency
  47 .Fa hz .
  48 The
  49 .Fa info
  50 argument is an allocated systimer structure; the
  51 .Fa func
  52 argument is the function to call, with argument
  53 .Fa data .
  54 .Pp
  55 The
  56 .Fn systimer_init_periodic_nq
  57 function initializes a systimer callback function to be called at a frequency
  58 .Fa hz .
  59 Unlike the
  60 .Fn systimer_init_periodic
  61 function, the
  62 .Fn systimer_init_periodic_nq
  63 function's callback is only called once at a given time, even if delays caused
  64 multiple time intervals to have occured.
  65 .Pp
  66 The
  67 .Fn systimer_adjust_periodic
  68 function changes the frequency at which a systimer's callback is invoked. The
  69 current time interval is not affected. The
  70 .Fa hz
  71 argument specifies the new frequency.
  72 .Pp
  73 The
  74 .Fn systimer_init_oneshot
  75 function arranges for a systimer callback function
  76 .Fa func
  77 to be invoked with argument
  78 .Fa data
  79 once, after at least
  80 .Fa us
  81 microseconds.
  82 .Sh EXAMPLE
  83 A simple example of using a one-short systimer to call a function after a short
  84 time:
  85 .Bd -literal
  86 ...
  87 static struct systimer short_st;
  88 char *str = "goodbye!";
  89 ...
  90 systimer_init_oneshot(&short_st, panic, str, 1000);
  91 ...
  92 .Ed
  93 .Sh FILES
  94 The systimer implementation is in
  95 .Pa /sys/kern/kern_systimer.c .
  96 .Sh SEE ALSO
  97 .Xr callout 9
  98 .Sh HISTORY
  99 Systimers first appeared in
 100 .Dx 1.0 .
 101