From c7c75b04967b6e9f120bea16759b00d5d4633961 Mon Sep 17 00:00:00 2001 From: josch Date: Fri, 18 May 2012 20:28:13 +0200 Subject: [PATCH] added README --- README.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..02b0211 --- /dev/null +++ b/README.md @@ -0,0 +1,62 @@ +Overview +======== + +Count or execute a program with an overall precise interval. Counting or +execution does not "fall behind" over time. The overall frequency will stay the +same and there will be no cumulative timing error. + +This script is just a convenience wrapper around the sleepenh program. + +Requirements +============ + +POSIX shell and sleepenh + +Features +======== + + * interval will stay the same on average and the counter will not "fall behind" + * count upward or downward + * specify interval length as a floating point number of seconds including fractions of one second + * begin to count at given integer and count for a specific number of times or until infinity + * print nothing at all + * execute a program at every step, optionally by forking it from the script for programs possibly running longer than the given interval + +Usage +===== + +Usage: periodic [ARGS] [COMMAND] + +It counts upward (incrementing by 1, default) or downward (decrementing by 1, +-d) starting at integer BEGIN (-b, default: 0) with a configurable floating +point interval of SECS seconds (-n, default 1.0) until infinity (default) or up +to a maximum number of COUNT intervals (-c). It can operate silently and not +print this counter (-s). It optionally executes a COMMAND per interval which it +can also fork (-f) in case the command is expected to take longer than SECS +seconds. + + -f fork COMMAND + -s silent, do not print counter + -d count downward (default: upward) + -n SECS interval of SECS in floating point (default: 1.0) + -c COUNT only run for COUNT interval(s) (default: -1 = infinity) + -b BEGIN start counting at BEGIN (default: 0) + -h print this help message + +History +======= + +I just wanted a program that reliably counted with a given frequency without +suffering from cumulative timing errors. I did not want to accept the small +delays that are adding up each time in a "while sleep(1)" loop. Being +instructed to count up to a million with a frequency of 1 Hz, the total +execution time should equal exactly one million seconds. + +Apparently such a trivial program didnt exist, but there is the sleepenh +program which is able to sleep for just the amount of time that the execution +is done in with an overall precise interval. Therefor I built a script around +that utility. + +watch(1) comes very close to what I do but it can only run in fullscreen, +doesnt go faster than 10Hz and doesnt allow the programs it executes to take +longer than its interval.