Nut upsdev - Jul 2016 - Proposal for technique to stop a timer at any moment

Dear list, I would like to propose a set of patches which make it possible 
for a upssched-cmd script to stop a timer at an arbitrary moment. If you 
find this of interest, I will submit a set of patches to 2.7.4.

Roger


Introduction
------------

The comments at the top of upssched.c say << * timers can be cancelled at
any
time before they trigger >>. It would be very useful if this were true,
but
unfortunately as Charles Lepple says in 
https://lists.alioth.debian.org/pipermail/nut-upsuser/2016-June/010177.html
<<
...timers are internal to upssched, and the only way to cancel them is through 
an event listed in the configuration file. >>

A general technique for stopping timers would be very useful for those who rely 
on the script upssched-cmd to provide their system shutdown logic.

Proposal
--------

I would like to propose a set of patches which make it possible to stop a timer 
at an arbitrary moment. The technique is very general in nature: it consists of 
sending signals USR1 and USR2 to the UPS's managed by upsd. Process upsd 
remembers the signals on behalf of the UPS's and passes them to upsmon when 
polled.  Signals USR1 and USR2 extend the set of notify types known by upsmon. 
The signal events may lead to notifications and calls of upssched.  In 
upssched.conf the AT declarations are extended to include USR1 and USR2 events, 
thus allowing declarations such as

  AT SIGUSR1 * CANCEL-TIMER shutdown-timer

Such a declaration is activated in upssched-cmd with a Bash command such 
as "killall -SIGUSR1 upsd" .

Patches
-------

My patches are generated using command

  diff -rup ./nut-2.7.4 ./nut-2.7.4.dev

where nut-2.7.4 is the directory created when unzipping nut-2.7.4.tar.gz .

Documentation
-------------

I propose submitting the documentation changes as plain text editorial 
comments.

The NUT User Manual Chapter 7.2. "The advanced approach, using
upssched"
http://networkupstools.org/docs/user-manual.chunked/ar01s07.html#_the_advanced_approach_using_upssched
is the subject of issue 293 "Improve upssched example in
documentation".
I propose an example showing how to monitor an unreliable UPS.
https://github.com/networkupstools/nut/issues/293

Debugging
---------

I find it convenient to be able to turn on/up/down/off the debugging level 
without touching the upsd process.  I do this by setting the required debugging 
depth in optional file <config-path>/NUT_DEBUG_LEVEL .  I include the
required
patch to common.c - perhaps this technique will be useful to others.

Testing
-------

The proposed patches to 2.7.4 have been tested on openSUSE 13.1 Evergreen 
long term support with an Eaton ECO 1600 and a tired MGE Ellipse 1500.

Programming style
-----------------

10 years of my career were spent programming in assembler on large process 
control systems.  I have also programmed in many high level languages such 
as APL, Algol, ML, Prolog, Erlang,.. but never in C.  However I have a 
copy of K&R, and Stevens' "Programming in the UNIX
Environment", and I
have tried as far as possible, and with the help of the NUT emacs style 
function to follow the NUT C style, although the diff program does not 
make this clear.