gRule.py

#!/usr/local/bin/python
#
#                               Copyright 2002
#                                     by
#                        The Board of Trustees of the
#                     Leland Stanford Junior University.
#                            All rights reserved.
#

__facility__ = "Online"
__abstract__ = "Classes for defining rules"
__author__   = "R. Claus <Claus@SLAC.Stanford.edu> SLAC - GLAST LAT I&T/Online"
__date__     = ("$Date: 2005/02/04 18:27:04 $").split(' ')[1]
__version__  = "$Revision: 2.4 $"
__credits__  = "SLAC"

import LATTE.copyright_SLAC


import               gGroup
import logging as    log
import LATTE.dispatch.dispatcher as dispatcher

class GruleBase(object):
  """\brief Base rule class for use when no rule is appropriate.

  """
  def __init__(self):
    pass
  def evaluate(self, value, attr, node=None):
    pass


class Grule(GruleBase):
  """\brief Base class for describing rules.

  """
  def __init__(self, name, subsystem, category, enabled, continuous = False):
    """Constructor.
      \param name       Rule name
      \param subsystem  Subsystem gGroup to which the rule belongs
      \param category   Category gGroup to which the rule belongs
      \param enabled    Flag indicating whether rule is enabled
      \param continuous Flag indicating whether rule can fire repeatedly

    """
    self.__name       = name
    self.__subsystem  = subsystem
    self.__category   = category
    self.__enabled    = enabled
    self.__continuous = continuous
    self.__fired      = {}  # A dict of node:bool pairs indicating if a partic node has fired.
    self.__actions    = {}
    # init self.__fired
    self.__fired[None]= False

  def _eval_(self, value, attr, node):
    """Base method called from derived classes.  
    determine whether or not this rule can fire or not.

    \return a tuple containing the value of the test and whether the rule can fire or not.
    """
    key = (node, attr)
    # print "baseEval: ", self.__continuous, self.__fired.has_key(key)
    
    if ( (self.__continuous) or\
         (not self.__fired.has_key(key)) or\
         (not self.__continuous and not self.__fired[key]) ):
      return (value, True)
    else:
      return (value, False)

  def evaluate(self, value, attr, node=None):
    """This method is called to evaluate the rule on 'value'

    \param value Value to be evaluated.
    \param attr  Attribute object whose \a value is being evaluated.

    \return Result of the evaluation, if any.

    """
    if self.__subsystem.enabled() and \
       self.__category.enabled()  and \
       self.__enabled:
      return self._eval_(value, attr, node)
    else:
      return (value, False)

  def name(self):
    """Method to retrieve the rule's name

    \return Rule's name.

    """
    return self.__name

  def subsystem(self):
    """Method for discovering this rule's subsystem

    \return Rule's subsystem.

    """
    return self.__subsystem

  def category(self):
    """Method for discovering this rule's category

    \return Rule's category.

    """
    return self.__category

  def enabled(self):
    """Method for discovering whether this rule is enabled

    \return Whether this rule is enabled or not.

    """
    return self.__enabled

  def enable(self):
    """Method used to enable evaluation of this rule

    """
    self.__enabled = True

  def disable(self):
    """Method used to disable evaluation of this rule

    """
    self.__enabled = False

  def reset(self, node=None):
    """Method used to reenable evaluation of this rule in the case of
    noncontinuous mode after it has been violated

    """
    self.__fired[node] = False
  
  def fire(self, node=None):
    """Method used to tell the rule it has fired
    """
    self.__fired[node] = True
  
  def fired(self, node=None):
    """Method for discovering whether this rule has fired
    
    \return Whether this rule has fired or not
    """
    if node not in self.__fired:
      return False
    else:
      return self.__fired[node]

  def registerAction(self, action, method, sender=dispatcher.Any):
    """Associate and action with a user \a method, optionally specifying a \a sender.
    If a \a sender is not specified, the rule \a action may be fired for all registers
    which declare its rule to be the rule of this \a action. If an attribute is
    specified as the \a sender then only if the evaluation of that specific attribute
    causes the \a action to be fired the \a method will be called.

    \param action A string that represents the action to be taken.
                  This is specified under the <actions> tag in the schema/configuration.
    \param method A user method visible to the current context.
    \param sender Optional parameter that specifies the sender of the action registration.
                  If specifed, only the sendAction requests which specify the same sender
                  will be honored. Defaults to dispatcher.Any.

    """
    if action not in self.__actions:
      log.error("Unable to register action %s, not specified in the configuration." % action)
    else:
      dispatcher.connect(method, signal=action, sender=sender)

  def setActions(self, actions):
    """Convenience method that gets called from the rule constructor
    that defines the action names (which is read from the schema/configuration).

    \param actions A list containing the action names.

    """
    self.__actions = actions

  def sendAction(self, action, sender, *arguments, **named):
    """Called from the rule evaluation method to fire the appropriate alarm action.

    \param action     A string that represents the action to be taken.
                      This is specified under the <actions> tag in the schema/configuration.
    \param sender     The sender that made the rule firing request. This is usually the
                      attribute which is being evaluated.
    \param *arguments An optional list of arguments which gets passed to the action method.

    \return A list of tuple pairs [(receiver, response), ... ]
    """
    return dispatcher.send(action, sender, *arguments, **named)

  def clearAllActions(self):
    """
    Forces all registered actions to be cleared.
    If this is not done and the scripts re-register their
    actions there may be extraneous rule action firings.
    """
    dispatcher.connections = {}

  def unregisterAction(self, action, method, sender=dispatcher.Any):
    """Reverse of registerAction, disassociates the action from the method.

   \param action A string that represents the action to be taken.
                  This is specified under the <actions> tag in the schema/configuration.
    \param method A user method visible to the current context.
    \param sender Optional parameter that specifies the sender of the action registration.
                  If specifed, only the sendAction requests which specify the same sender
                  will be honored. Defaults to dispatcher.Any.
    """
    dispatcher.disconnect(method, action, sender)

class GruleLimit(Grule):
  """\brief Rule class that limits a passed in value to given limits.

  """
  def __init__(self, name, subsystem, category, enabled, continuous,
               low, high):
    """Limit rule constructor.

      \param name             Rule name
      \param subsystem        Subsystem gGroup to which the rule belongs
      \param category         Category gGroup to which the rule belongs
      \param enabled          Flag indicating whether rule is enabled
      \param continuous       Flag indicating whether rule can fire repeatedly
      \param low              Low limit
      \param high             High limit

    """
    Grule.__init__(self, name, subsystem, category, enabled, continuous)
    self.__low  = low
    self.__high = high

  def _eval_(self, value, attr, node):
    """Evaluate the rule.
    """
    if   value < self.__low:
      log.warning("%s rule: value is below low limit"  % self.name())
    elif value > self.__high:
      log.warning("%s rule: value is above high limit" % self.name())

class GruleAlarms(Grule):
  """\brief Alarm rule

  If the value falls below the yellow or red lower limit or it exceeds
  the yellow or red upped limit the appropriate registered action is
  fired.
  """
  def __init__(self, name, subsystem, category, enabled, continuous,
               yellowUpperLimit, yellowLowerLimit,
               redUpperLimit, redLowerLimit, actions=[]):
    """Alarm rule constructor.

      \param name             Rule name
      \param subsystem        Subsystem gGroup to which the rule belongs
      \param category         Category gGroup to which the rule belongs
      \param enabled          Flag indicating whether rule is enabled
      \param continuous       Flag indicating whether rule can fire repeatedly
      \param yellowUpperLimit Yellow alarm upper limit
      \param yellowLowerLimit Yellow alarm lower limit
      \param redUpperLimit    Red alarm upper limit
      \param redLowerLimit    Red alarm lower limit
    """

    Grule.__init__(self, name, subsystem, category, enabled, continuous)
    self.__yellowLowerLimit = yellowLowerLimit
    self.__yellowUpperLimit = yellowUpperLimit
    self.__redLowerLimit = redLowerLimit
    self.__redUpperLimit = redUpperLimit
    self.setActions(actions)

  def _eval_(self, value, attr, node):
    """Alarm rule evaluation method.

    If the red alarm is fired then the yellow alarm does not get fired.
    """
    action = None
    key = (node, attr)
    if value < self.__redLowerLimit or value > self.__redUpperLimit:
      action = "redAction"
    elif value < self.__yellowLowerLimit or value > self.__yellowUpperLimit:
      action = "yellowAction"
    else:
      self.reset(key)
    temp, canFire = Grule._eval_(self, value, attr, node)
    if action is not None and canFire:
      self.fire(key)
      self.sendAction(action, attr, value, node=node)

---