# Copyright 2013-2015 ARM Limited # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # """ This module wraps louie signalling mechanism. It relies on modified version of loiue that has prioritization added to handler invocation. """ import logging from contextlib import contextmanager from louie import dispatcher from wa.utils.types import prioritylist logger = logging.getLogger('dispatcher') class Signal(object): """ This class implements the signals to be used for notifiying callbacks registered to respond to different states and stages of the execution of workload automation. """ def __init__(self, name, description='no description', invert_priority=False): """ Instantiates a Signal. :param name: name is the identifier of the Signal object. Signal instances with the same name refer to the same execution stage/stage. :param invert_priority: boolean parameter that determines whether multiple callbacks for the same signal should be ordered with ascending or descending priorities. Typically this flag should be set to True if the Signal is triggered AFTER an a state/stage has been reached. That way callbacks with high priorities will be called right after the event has occured. """ self.name = name self.description = description self.invert_priority = invert_priority def __str__(self): return self.name __repr__ = __str__ def __hash__(self): return id(self.name) RUN_STARTED = Signal('run-started', 'sent at the beginning of the run') RUN_INITIALIZED = Signal('run-initialized', 'set after the run has been initialized') RUN_ABORTED = Signal('run-aborted', 'set when the run has been aborted due to a keyboard interrupt') RUN_FAILED = Signal('run-failed', 'set if the run has failed to complete all jobs.' ) RUN_COMPLETED = Signal('run-completed', 'set upon completion of the run (regardless of whether or not it has failed') RUN_FINALIZED = Signal('run-finalized', 'set after the run has been finalized') JOB_STARTED = Signal('job-started', 'set when a a new job has been started') JOB_ABORTED = Signal('job-aborted', description=''' sent if a job has been aborted due to a keyboard interrupt. .. note:: While the status of every job that has not had a chance to run due to being interrupted will be set to "ABORTED", this signal will only be sent for the job that was actually running at the time. ''') JOB_FAILED = Signal('job-failed', description='set if the job has failed') JOB_RESTARTED = Signal('job-restarted') JOB_COMPLETED = Signal('job-completed') JOB_FINALIZED = Signal('job-finalized') ERROR_LOGGED = Signal('error-logged') WARNING_LOGGED = Signal('warning-logged') # These are paired events -- if the before_event is sent, the after_ signal is # guaranteed to also be sent. In particular, the after_ signals will be sent # even if there is an error, so you cannot assume in the handler that the # device has booted successfully. In most cases, you should instead use the # non-paired signals below. BEFORE_RUN_INIT = Signal('before-run-init', invert_priority=True) SUCCESSFUL_RUN_INIT = Signal('successful-run-init') AFTER_RUN_INIT = Signal('after-run-init') BEFORE_FLASHING = Signal('before-flashing', invert_priority=True) SUCCESSFUL_FLASHING = Signal('successful-flashing') AFTER_FLASHING = Signal('after-flashing') BEFORE_BOOT = Signal('before-boot', invert_priority=True) SUCCESSFUL_BOOT = Signal('successful-boot') AFTER_BOOT = Signal('after-boot') BEFORE_TARGET_CONNECT = Signal('before-target-connect', invert_priority=True) SUCCESSFUL_TARGET_CONNECT = Signal('successful-target-connect') AFTER_TARGET_CONNECT = Signal('after-target-connect') BEFORE_TARGET_DISCONNECT = Signal('before-target-disconnect', invert_priority=True) SUCCESSFUL_TARGET_DISCONNECT = Signal('successful-target-disconnect') AFTER_TARGET_DISCONNECT = Signal('after-target-disconnect') BEFORE_WORKLOAD_SETUP = Signal( 'before-workload-setup', invert_priority=True) SUCCESSFUL_WORKLOAD_SETUP = Signal('successful-workload-setup') AFTER_WORKLOAD_SETUP = Signal('after-workload-setup') BEFORE_WORKLOAD_EXECUTION = Signal( 'before-workload-execution', invert_priority=True) SUCCESSFUL_WORKLOAD_EXECUTION = Signal('successful-workload-execution') AFTER_WORKLOAD_EXECUTION = Signal('after-workload-execution') BEFORE_WORKLOAD_RESULT_UPDATE = Signal( 'before-workload-result-update', invert_priority=True) SUCCESSFUL_WORKLOAD_RESULT_UPDATE = Signal( 'successful-workload-result-update') AFTER_WORKLOAD_RESULT_UPDATE = Signal('after-workload-result-update') BEFORE_WORKLOAD_TEARDOWN = Signal( 'before-workload-teardown', invert_priority=True) SUCCESSFUL_WORKLOAD_TEARDOWN = Signal('successful-workload-teardown') AFTER_WORKLOAD_TEARDOWN = Signal('after-workload-teardown') BEFORE_OVERALL_RESULTS_PROCESSING = Signal( 'before-overall-results-process', invert_priority=True) SUCCESSFUL_OVERALL_RESULTS_PROCESSING = Signal( 'successful-overall-results-process') AFTER_OVERALL_RESULTS_PROCESSING = Signal( 'after-overall-results-process') class CallbackPriority(object): EXTREMELY_HIGH = 30 VERY_HIGH = 20 HIGH = 10 NORMAL = 0 LOW = -10 VERY_LOW = -20 EXTREMELY_LOW = -30 def __init__(self): raise ValueError('Cannot instantiate') class _prioritylist_wrapper(prioritylist): """ This adds a NOP append() method so that when louie invokes it to add the handler to receivers, nothing will happen; the handler is actually added inside the connect() below according to priority, before louie's connect() gets invoked. """ def append(self, *args, **kwargs): pass def connect(handler, signal, sender=dispatcher.Any, priority=0): """ Connects a callback to a signal, so that the callback will be automatically invoked when that signal is sent. Parameters: :handler: This can be any callable that that takes the right arguments for the signal. For most signals this means a single argument that will be an ``ExecutionContext`` instance. But please see documentation for individual signals in the :ref:`signals reference `. :signal: The signal to which the handler will be subscribed. Please see :ref:`signals reference ` for the list of standard WA signals. .. note:: There is nothing that prevents instrumentation from sending their own signals that are not part of the standard set. However the signal must always be an :class:`wlauto.core.signal.Signal` instance. :sender: The handler will be invoked only for the signals emitted by this sender. By default, this is set to :class:`louie.dispatcher.Any`, so the handler will be invoked for signals from any sender. :priority: An integer (positive or negative) the specifies the priority of the handler. Handlers with higher priority will be called before handlers with lower priority. The call order of handlers with the same priority is not specified. Defaults to 0. .. note:: Priorities for some signals are inverted (so highest priority handlers get executed last). Please see :ref:`signals reference ` for details. """ if getattr(signal, 'invert_priority', False): priority = -priority senderkey = id(sender) if senderkey in dispatcher.connections: signals = dispatcher.connections[senderkey] else: dispatcher.connections[senderkey] = signals = {} if signal in signals: receivers = signals[signal] else: receivers = signals[signal] = _prioritylist_wrapper() receivers.add(handler, priority) dispatcher.connect(handler, signal, sender) def disconnect(handler, signal, sender=dispatcher.Any): """ Disconnect a previously connected handler form the specified signal, optionally, only for the specified sender. Parameters: :handler: The callback to be disconnected. :signal: The signal the handler is to be disconnected form. It will be an :class:`wlauto.core.signal.Signal` instance. :sender: If specified, the handler will only be disconnected from the signal sent by this sender. """ dispatcher.disconnect(handler, signal, sender) def send(signal, sender=dispatcher.Anonymous, *args, **kwargs): """ Sends a signal, causing connected handlers to be invoked. Paramters: :signal: Signal to be sent. This must be an instance of :class:`wlauto.core.signal.Signal` or its subclasses. :sender: The sender of the signal (typically, this would be ``self``). Some handlers may only be subscribed to signals from a particular sender. The rest of the parameters will be passed on as aruments to the handler. """ return dispatcher.send(signal, sender, *args, **kwargs) # This will normally be set to log_error() by init_logging(); see wa.framework/log.py. # Done this way to prevent a circular import dependency. log_error_func = logger.error def safe_send(signal, sender=dispatcher.Anonymous, propagate=[KeyboardInterrupt], *args, **kwargs): """ Same as ``send``, except this will catch and log all exceptions raised by handlers, except those specified in ``propagate`` argument (defaults to just ``[KeyboardInterrupt]``). """ try: send(singnal, sender, *args, **kwargs) except Exception as e: if any(isinstance(e, p) for p in propagate): raise e log_error_func(e) @contextmanager def wrap(signal_name, sender=dispatcher.Anonymous, safe=False, *args, **kwargs): """Wraps the suite in before/after signals, ensuring that after signal is always sent.""" signal_name = signal_name.upper().replace('-', '_') send_func = safe_send if safe else send try: before_signal = globals()['BEFORE_' + signal_name] success_signal = globals()['SUCCESSFUL_' + signal_name] after_signal = globals()['AFTER_' + signal_name] except KeyError: raise ValueError('Invalid wrapped signal name: {}'.format(signal_name)) try: send_func(before_signal, sender, *args, **kwargs) yield send_func(success_signal, sender, *args, **kwargs) finally: send_func(after_signal, sender, *args, **kwargs)