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 July 3, 2020
  20 .Dt SYSTIMER 9
  21 .Os
  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" "systimer_func_t func" "void *data" "int64_t freq"
  32 .Ft void
  33 .Fn systimer_init_periodic_nq "systimer_t info" "systimer_func_t func" "void *data" "int64_t freq"
  34 .Ft void
  35 .Fn systimer_adjust_periodic "systimer_t info" "int64_t freq"
  36 .Ft void
  37 .Fn systimer_init_oneshot "systimer_t info" "systimer_func_t func" "void *data" "int64_t us"
  38 .Sh DESCRIPTION
  39 Systimers invoke callbacks at either fixed frequencies or after time delays.
  40 The callbacks are invoked in an interrupt thread and should only be used
  41 for limited work.
  42 .Pp
  43 The
  44 .Fn systimer_init_periodic
  45 function initializes a systimer callback function to be called at frequency
  46 .Fa freq .
  47 The
  48 .Fa info
  49 argument is an allocated systimer structure; the
  50 .Fa func
  51 argument is the function to call, with argument
  52 .Fa data .
  53 .Pp
  54 The
  55 .Fn systimer_init_periodic_nq
  56 function initializes a systimer callback function to be called at a frequency
  57 .Fa freq .
  58 Unlike the
  59 .Fn systimer_init_periodic
  60 function, the
  61 .Fn systimer_init_periodic_nq
  62 function's callback is only called once at a given time, even if delays caused
  63 multiple time intervals to have occurred.
  64 .Pp
  65 The
  66 .Fn systimer_adjust_periodic
  67 function changes the frequency at which a systimer's callback is invoked.
  68 The
  69 current time interval is not affected.
  70 The
  71 .Fa freq
  72 argument specifies the new frequency.
  73 .Pp
  74 The
  75 .Fn systimer_init_oneshot
  76 function arranges for a systimer callback function
  77 .Fa func
  78 to be invoked with argument
  79 .Fa data
  80 once, after at least
  81 .Fa us
  82 microseconds.
  83 .Sh FILES
  84 The systimer implementation is in
  85 .Pa /sys/kern/kern_systimer.c .
  86 .Sh EXAMPLES
  87 A simple example of using a one-short systimer to call a function after a short
  88 time:
  89 .Bd -literal -offset indent
  90 \&...
  91 static struct systimer short_st;
  92 char *str = "goodbye!";
  93 \&...
  94 systimer_init_oneshot(&short_st, panic, str, 1000);
  95 \&...
  96 .Ed
  97 .Sh SEE ALSO
  98 .Xr callout 9
  99 .Sh HISTORY
 100 Systimers first appeared in
 101 .Dx 1.0 .