seSuiteBase.py

Go to the documentation of this file.

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

__facility__ = "Online"
__abstract__ = "Script engine suite base class"
__author__   = "S. Tuvi <stuvi@SLAC.Stanford.edu> SLAC - GLAST LAT I&T/Online"
__date__     = "2005/07/15 00:08:27"
__updated__  = "$Date: 2006/04/04 02:27:50 $"
__version__  = "$Revision: 1.8 $"
__release__  = "$Name: HEAD $"
__credits__  = "SLAC"

import LICOS.copyright_SLAC

from threading import Event
import logging as log

from LICOS.scriptEngine.FSM import FSM
from LICOS.scriptEngine     import rcUtil
from LICOS.lib.scriptEngine.seAppBase import seAppBase

class seSuiteBase(FSM):
  """!\brief Script engine base class for suites.

  """

  # private class level variables
  __suiteStack = []

  def __init__(self, common):
    """!\brief seSuiteBase constructor

    \param common ScriptEngineCommon instance
    """
    FSM.__init__(self, 'SUITE STOPPED', None)
    self.set_default_transition(                                  self.error,     None)
    self.add_transition        ('SETUP',     'SUITE STOPPED',     self.seSetup,   'SUITE IN PROGRESS')
    self.add_transition        ('RUN',       'SUITE IN PROGRESS', self.seRun,     'SUITE COMPLETE')
    self.add_transition        ('STOP_RUN',  'SUITE COMPLETE',    self.seStopRun, 'SUITE STOPPED')
    self.add_transition        ('ABORT',     'SUITE IN PROGRESS', self.seAbort,   'SUITE STOPPED')
    self.add_transition        ('PAUSE',     'SUITE IN PROGRESS', self.sePause,   'SUITE PAUSED')
    self.add_transition        ('RESUME',    'SUITE PAUSED',      self.seResume,  'SUITE IN PROGRESS')

    self.common = common
    self.prefs = self.common.preferences()

    self.gui = common.getGUI()

    self.__suiteStart  = None
    self.__stopRequested = False
    self.__parentSuite = None
    self.__scriptSeq   = 0
    # Current suite's child script (could be an app or a suite)
    self.__script      = None
    self.__resumeEvent = Event()
    self.__paused      = False
    self.__suiteID     = None

  def getRunSequence(self):
    """!\brief Return the order of transitions for this type of application.

    \return A list of transitions
    """
    return ['SETUP', 'RUN', 'STOP_RUN']

  def doAbort(self):
    """!\brief Request stop of execution.

    \return Result of the transition
    """
    if self.__paused:
      status = self.doResume()
      if status is not None: return status
    if self.get_transition("ABORT", self.current_state)[1] is not None:
      return self.process('ABORT')

  def doPause(self):
    """!\brief Request pause of execution.

    \return Result of the transition
    """
    if self.get_transition("PAUSE", self.current_state)[1] is not None:
      return self.process('PAUSE')

  def doResume(self):
    """!\brief Request resume of execution.

    \return Result of the transition
    """
    if self.get_transition("RESUME", self.current_state)[1] is not None:
      return self.process('RESUME')

  def error(self):
    """!\brief This method is called when an undefined transition is requested.

    """
    log.error(self.__class__.__name__ + " - Undefined transition: %s from state %s" % \
            (self.input_symbol, self.current_state))

  def seSetup(self):
    """!\brief SETUP transition method

    Calls self.setup()

    \return None for success or
            False if there is an exception or
            status returned by the suite.
    """
    self.__paused = False
    self.__stopRequested = False
    self.__scriptSeq   = 0
    self.__updateGUI()

    # define the suiteStart script.
    # As it's part of this module, we don't have to call scriptLoad,
    #   but setParentSuite must be called.
    self.__suiteStart = suiteStart(self.common)
    self.__suiteStart.setParentSuite(self)

    return self.setup()

  def seRun(self):
    """!\brief RUN transition method

    Calls self.run()

    \return None for success or
            False if there is an exception or
            status returned by the suite.
    """
    self.__updateGUI()
    # run the suiteStart script.
    self.scriptRun(self.__suiteStart)
    return self.run()

  def sePause(self):
    """!\brief PAUSE transition method

    Calls self.pause()

    \return None for success or
            False if there is an exception or
            status returned by the suite.
    """
    if self.__resumeEvent.isSet():
      self.__resumeEvent.clear()
      self.gui.execGUImethodNR(self.gui.updateState, "PAUSING SUITE")
      if self.__script is not None and 'doPause' in dir(self.__script):
        status = self.__script.doPause()
        if status is not None: return status
    return self.pause()

  def seResume(self):
    """!\brief RESUME transition method

    Calls self.resume()

    \return None for success or
            False if there is an exception or
            status returned by the suite.
    """
    if self.__paused:
      if self.__script is not None and 'doResume' in dir(self.__script):
        self.__script.doResume()
      self.__resumeEvent.set()
      return self.resume()

  def seStopRun(self):
    """!\brief STOP_RUN transition method

    Calls self.stopRun()

    \return None for success or
            False if there is an exception or
            status returned by the suite.
    """
    if self.__paused:
      self.process('RESUME')
    self.__updateGUI()
    status =  self.stopRun()
    self.__suiteID     = None
    return status


  def seAbort(self):
    """!\brief ABORT transition method

    Calls self.abort()

    \return None for success or
            False if there is an exception or
            status returned by the suite.
    """
    self.setStopRequested()
    if self.__script is not None and 'doAbort' in dir(self.__script):
      self.__script.doAbort()
    return self.abort()

  def __updateGUI(self):
    """!\brief Update the state of the run on the GUI.

    """
    if self.gui is not None:
      self.gui.execGUImethodNR(self.gui.updateState, self.current_state)

  def setup(self):
    """!\brief Transition method to be overridden by the suite.

    """
    pass

  def stopRun(self):
    """!\brief Transition method to be overridden by the suite.

    """
    pass

  def pause(self):
    """!\brief Transition method to be overridden by the suite.

    """
    pass

  def resume(self):
    """!\brief Transition method to be overridden by the suite.

    """
    pass

  def abort(self):
    """!\brief Transition method to be overridden by the suite.

    """
    pass

  def scriptLoad(self, script, *args, **kwargs):
    """!\brief Load and instantiate an seAppBase or seSuiteBase based script.

    \param script Script module name or Python source path
    \param args   Positional arguments passed to the script
    \param kwargs Keyword arguments passed to the script

    \return Instantiated script object
    """
    (self.__module, self.__filename,
        self.__script) = rcUtil.scriptLoad(script, self.common,
                                        0, *args, **kwargs)
    if self.__script is not None:
      self.__script.setParentSuite(self)
    return self.__script

  def scriptRun(self, script=None):
    """!\brief Start the run of the specified script.

    \param script Instantiated script object.
                  If None, the last instantiated script is used.
    """
    if script == None:
      script = self.__script
    else:
      self.__script = script
    self.__scriptSeq += 1

    log.debug("script subclass: %s" % isinstance(script, seSuiteBase))
    if isinstance(script, seSuiteBase):
      script.setSuiteID(self.getSuiteID())

    self.__resumeEvent.set()
    rcUtil.scriptRun(script)
    if self.isPauseRequested():
      self.__updateGUI()
      self.setPaused(True)
      self.__resumeEvent.wait()
      self.setPaused(False)

  def getName(self):
    """!\brief Retrieve the class name of the script.

    \return Name of the script class
    """
    return self.__class__.__name__

  def getScript(self):
    """!\brief Retrieve the script object.

    \return Script object instance.
    """
    return self.__script

  def getType(self):
    """!\brief Return the type of test based on this class.

    Used for logging purposes.

    \return Test type
    """
    return 'Suite'

  def isStopRequested(self):
    """!\brief Is stop requested?

    \return Boolean flag indicating whether a stop was requested
    """
    return self.__stopRequested

  def setStopRequested(self):
    """!\brief Set the stop requested flag.

    """
    self.__stopRequested = True

  def isPauseRequested(self):
    """!\brief Is pause requested?

    \return Boolean flag indicating whether a pause was requested
    """
    return not self.__resumeEvent.isSet()

  def isPaused(self):
    """!\brief Retrieve the paused status of the script.

    \param paused Boolean indicating whether the script is paused or not
    """
    return self.__paused

  def setPaused(self, paused):
    """!\brief Mark the script and its parent suites as paused or unpaused.

    \param paused Boolean indicating whether the script is paused or not
    """
    self.__paused = paused
    if self.__parentSuite is not None:
      self.__parentSuite.setPaused(paused)

  def setParentSuite(self, suite):
    """!\brief Set the parent suite instance.

    \param Suite instance
    """
    self.__parentSuite = suite

  def getParentSuite(self):
    """!\brief Retrieve the parent suite instance.

    \return Suite instance
    """
    return self.__parentSuite

  def getParentSuiteName(self):
    """!\brief Retrieve the parent suite name.

    \return Parent suite name.
    """
    if self.__parentSuite is not None:
      return self.__parentSuite.getName()

  def isRunFromSuite(self):
    """!\brief Check if the script is being run from a suite.

    \return True  If the script is being run from a suite,
            False otherwise.
    """
    return self.__parentSuite is not None

  def getScriptSequence(self):
    """!\brief Retrieve the sequence number for the running suite script.

    The script sequence is incremented for each scriptRun called in the suite.
    This method is provided so that the suite author and the script engine
    can keep track of which script is the first script being run (which will
    have a script sequence of 1).

    \return Suite script sequence
    """
    return self.__scriptSeq

  def getSuiteID(self):
    """!\brief Retrieve the suite identifier

    As an aid to linking runs in suites together, a LICOS activity has
    the concept of a suite identifier.  This number is identically the
    runID of the first run of a suite (which is implemented in
    seSuiteBase.py).

    \return Suite identifier (integer string)
    """
    return self.__suiteID

  def setSuiteID(self, suiteID):
    """!\brief Set the suite identifier

    \param suiteID   Suite identifier (integer or numeric string)
    """
    self.__suiteID = str(suiteID)

  def setSessionVar(self, key, value):
    """!\brief Set a session variable.

    Do not use variable names beginning
    with the underscore ('_') character since these are reserved for ScriptEngine
    """
    sessionVars = self.common.getDBN()
    if sessionVars is not None:
      sessionVars[key] = value
    else:
      raise RuntimeError, "Database node does not exist"

  def getSessionVar(self, key):
    """!\brief Retrieve the values of the session variable indicated by \a key.

    \return Session variable value
    """
    sessionVars = self.common.getDBN()
    if sessionVars is not None and sessionVars.has_key(key):
      return sessionVars[key]
    else:
      return None

class suiteStart(seAppBase):
  """!\brief Dummy run to indicate that a suite has started
  """
  def __init__(self, common, fromVal=None, toVal=None):
    """!\brief suiteStart constructor.

    \param fromVal from value
    \param toVal   to value
    """
    seAppBase.__init__(self, common)
    self.__fromVal = fromVal
    self.__toVal = toVal

  def setup(self):
    """!\brief SETUP transition method.

    \return Transition result
    """

    return None

  def teardown(self):
    """!\brief START_RUN transition method

    Sets the suite identifier for the controlling suite
    """
    self.getParentSuite().setSuiteID(self.runId)

  def stopRun(self):
    """!\brief STOP_RUN transition method

    \return Transition result
    """
    self.setCompletionStatus(self.COMPL_STATUS_PASSED)
    return None

---