EpicsCA.alarm = class alarm
    alarm class for a PV:
run a user-supplied callback when a PV's value goes out of an acceptable range
 
quick synopsis:
   The supplied _callback_ will be run when a _comparison_ of the pv's value
   and a _trip point_ is True.  An optional _alert delay_ can be set to limit
   how frequently the callback is run
 
arguments:
   pvname             name of PV for which to set alarm
   trip_point         value of trip point
   comparison         a string for the comparison operation: one of
                          'eq', 'ne', 'le', 'lt', 'ge', 'gt'
                          '==', '!=', '<=', '<' , '>=', '>'
   callback           function to run when the comparison(value,trip_point) is True
   alert_delay        time (in seconds) to stay quiet after executing a callback.
                      this is a _minimum_ time, as it is checked only when a PVs value
                      actually changes.  See note below.
   notify_all_alarms  whether to call alarm callback even for "Alarm to Alarm"
                      transitions: where the pv was in an alarm state and changed value
                      to another alarm state.
                      This is normally False, so that the alarm callback is called only
                      when going from "No Alarm" to "Alarm" status.
 
   
example:
   >>> from EpicsCA import alarm, pend_event
   >>> def alarmHandler(pv=None,**kw):
   >>>     print 'Alarm!! ', pv.pvname, pv.value
   >>> alarm(pvname = 'XX.VAL',
   >>>       comparison='gt',
   >>>       callback = alarmHandler,
   >>>       trip_point=2.0,
   >>>       alert_delay=600)
   >>> while True:
   >>>     pend_event()
 
when 'XX.VAL' exceeds (is 'gt') 2.0, the alarmHandler will be called.
 
 
notes:
  alarm_delay:  The alarm delay avoids annoying over-notification by specifying a
                time to NOT send messages, even when a PV value is changing and
                out-of-range.  Since Epics callback are used to process events,
                the alarm state will only be checked when a PV's value changes.
  notify_all_alarms  This sets whether to notify on "Alarm to Alarm" transitions
                this is normally false, so that notifications only happen on
                transitions from No Alarm to Alarm.
                
                With "notify_all_alarms" True, the user callback is run when:
                   The PV value has changed.
                   The PV value is 'out-of-range' [ comparison(value,trip_point) is True]
                   It has been at least alarm_delay seconds since the callback was run.
 
                With "notify_all_alarms" False (the default), the user callback is run when:
                   The PV value has changed.
                   The PV value was 'in-range' [ comparison(value,trip_point) is False]
                   The PV value is 'out-of-range' [ comparison(value,trip_point) is True]
                   It has been at least alarm_delay seconds since the callback was run.                    
 
 
  callback function:  the user-supplied callback function should have the following
                keyword argument (using **kw is always recommended!):
 
                pv          will hold the EpicsCA pv object for the pv
                comparison  will hold the comparison used to define 'out of range'
                trip_point  will hold the trip point used to define 'out of range'
 
  Methods defined here:
__init__(self, pvname=None, trip_point=None, comparison=None, callback=None, notify_all_alarms=False, alert_delay=0, **kw)
Data and other attributes defined here:
valid_comparisons = {'!=': '__ne__', '<': '__lt__', '<=': '__le__', '==': '__eq__', '>': '__gt__', '>=': '__ge__', 'eq': '__eq__', 'ge': '__ge__', 'gt': '__gt__', 'le': '__le__', ...}