source: SHX/trunk/src/SeismicHandler/core/modules/Messages.py @ 153

# -*- coding: utf-8 -*-
#
# Copyright (C) 2008-2010 Marcus Walther (walther@szgrf.bgr.de)
#
# This file is part of Seismic Handler eXtended (SHX)
# Full details can be found at project website http://www.seismic-handler.org/
#
# SHX is free software; you can redistribute it and/or modify
# it under the terms of the GNU LESSER GENERAL PUBLIC LICENSE as published by
# the Free Software Foundation; either version 3 of the License, or
# (at your option) any later version.
#
# SHX is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with SHX (see license.txt); if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA

"""Events class

    - simple event manager
"""

from SeismicHandler.core.error import Error
from SeismicHandler.core.log import logging

class NotifierNotCallableError(Error):
    def __init__(self):
        Error.__init__(self)

    def __str__(self):
        return "notifier must be callable!"

class Message(object):
    """Event class.

    Implemented as multiton, so that equal id's are represented by identical
    instances.
    """

    _instances = {}

    def __new__(cls, id):
        if not id in cls._instances.keys():
            cls._instances[id] = object.__new__(cls, id)

        return cls._instances[id]

    def __init__(self, id):
        self.name = id
        self.done = False

class MessageController(object):
    """Events manager

    Subscribing to events:
    >>> def x(e, x): print x*2
    >>> e = MessageController()
    >>> foo = Message("foo")
    >>> bar = Message("bar")
    >>> e.subscribe(foo, x)
    >>> e.subscribe(bar, x)
    >>> sorted([i.name for i in e.events])
    ['bar', 'foo']
    >>> e.events[bar] #doctest: +ELLIPSIS
    [<function x at 0x...]
    >>> e.events[foo] #doctest: +ELLIPSIS
    [<function x at 0x...]

    Now trigger an event:
    >>> e.trigger(foo, 2)
    4
    >>> e.trigger(bar, 7)
    14

    Events can be blocked to prevent propagation:
    >>> e.block(foo)
    >>> e.trigger(foo, 2)
    >>> e.trigger(foo, 4)

    If an event is unblocked, pending events can be processed then or discarded.
    Running only the last one is default, None skips processing in total. Here
    we run all pending events with their associated data:
    >>> e.unblock(foo, process="all")
    4
    8

    Now only the last event queued:
    >>> e.block(foo)
    >>> e.trigger(foo, 3)
    >>> e.trigger(foo, 5)
    >>> e.unblock(foo)
    10

    A function can be unsubscribed from an event:
    >>> e.unsubscribe(x, foo)
    >>> e.trigger(foo, 111)
    >>> e.trigger(bar, 6)
    12

    To unsubscribe a function in total, you don't have to know which
    subscriptions are active:
    >>> e.unsubscribe(x)
    >>> e.trigger(foo, 99)
    >>> e.trigger(bar, 6)
    """

    # standard events
    TRACEUPDATE = "traceupdate"
    REDRAW = "redraw"
    COMMANDRUN = "cmdrun"
    INFOIDXUPDATE = "infoindexupdate"

    events = {}
    blocked = set()
    queue = []

    def __init__(self):
        self.logger = logging.getLogger("modules.events")

    def subscribe(self, events, notify):
        """subscribe to events list

            - notify must contain a call back function
        """

        if not callable(notify):
            raise NotifierNotCallableError

        # change type to list if not iterable
        if not hasattr(events, "__iter__"):
            events = [events, ]

        for e in events:
            try:
                self.events[e].append(notify)
            except KeyError:
                self.events[e] = [notify]

            self.logger.debug("'%s' subscribed to event '%s'." % (notify, e.name))

    def trigger(self, event, *data):
        """trigger event """

        if event in self.blocked:
            # save blocked event for later use
            self.queue.append([event, data])
            self.logger.debug("Event '%s' triggered (but blocked)." % event.name)
            return

        self.logger.debug("Event '%s' triggered." % event.name)

        if not self.events.has_key(event):
            self.logger.debug("Event '%s' not found." % event.name)
            return False

        for i in self.events[event]:
            i(event, *data)

            # notified function has the possibility to stop further processing
            if event.done:
                self.logger.debug("Event '%s' propagation stopped by %s." % (event.name, i))
                break

    def unsubscribe(self, notify, events=None):
        """unsubscribe notifier from events """

        if not events:
            events = self.events

        if not hasattr(events, "__iter__"):
            events = [events, ]

        for e in events:
            if notify in self.events[e]:
                try:
                    self.logger.debug("'%s' unsubscribed from event '%s'." % (notify, e.name))
                    self.events[e].remove(notify)
                except (ValueError):
                    pass

    def block(self, event):
        """set event on block stage, this means, that the event won't be propagated
        """

        self.blocked.update([event])

    def unblock(self, event, process="last"):
        """unblock event propagation

            @param process:
                control what to do with pending events:
                None   - discard
                "last" - only trigger last one
                "all"  - trigger all
        """

        # unblock event
        try:
            self.blocked.remove(event)
        except KeyError:
            return

        # check if event occurred and maybe trigger it
        # work on a copy of queue
        if process == "last":
            # reverse order
            cqueue = self.queue[::-1]
        else:
            # normal copy
            cqueue = self.queue[:]

        for pending in cqueue:
            if event != pending[0]:
                continue

            self.queue.remove(pending)

            # skip if requested
            if not process:
                continue

            # alter state if only last one should be processed
            if process == "last":
                process = None

            self.trigger(pending[0], *pending[1])

MessageService = MessageController()

if __name__ == "__main__":
    import doctest
    doctest.testmod()