Source code for xl.event

# Copyright (C) 2008-2010 Adam Olsen
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2, or (at your option)
# any later version.
#
# This program 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 General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
#
#
# The developers of the Exaile media player hereby grant permission
# for non-GPL compatible GStreamer and Exaile plugins to be used and
# distributed together with GStreamer and Exaile. This permission is
# above and beyond the permissions granted by the GPL license by which
# Exaile is covered. If you modify this code, you may extend this
# exception to your version of the code, but you are not obligated to
# do so. If you do not wish to do so, delete this exception statement
# from your version.

"""
Provides a signals-like system for sending and listening for 'events'


Events are kind of like signals, except they may be listened for on a
global scale, rather than connected on a per-object basis like signals
are. This means that ANY object can emit ANY event, and these events may
be listened for by ANY object.

Events should be emitted AFTER the given event has taken place. Often the
most appropriate spot is immediately before a return statement.
"""

from inspect import ismethod
import logging
import re
import threading
import time
import types
import weakref
from gi.repository import GLib

# define this here so the interpreter doesn't complain
EVENT_MANAGER = None

logger = logging.getLogger(__name__)


class Nothing:
    pass


_NONE = Nothing()  # used by event for a safe None replacement

# Assumes that this module was imported on main thread
_UiThread = threading.current_thread()


[docs]def log_event(evty, obj, data): """ Sends an event. :param evty: the *type* or *name* of the event. :type evty: string :param obj: the object sending the event. :type obj: object :param data: some data about the event, None if not required :type data: object """ global EVENT_MANAGER e = Event(evty, obj, data) EVENT_MANAGER.emit(e)
[docs]def add_callback(function, evty=None, obj=None, *args, **kwargs): """ Adds a callback to an event You should ALWAYS specify one of the two options on what to listen for. While not forbidden to listen to all events, doing so will cause your callback to be called very frequently, and possibly may cause slowness within the player itself. :param function: the function to call when the event happens :type function: callable :param evty: the *type* or *name* of the event to listen for, eg `tracks_added`, `cover_changed`. Defaults to any event if not specified. :type evty: string :param obj: the object to listen to events from, e.g. `exaile.collection` or `xl.covers.MANAGER`. Defaults to any object if not specified. :type obj: object :param destroy_with: (keyword arg only) If specified, this event will be detached when the specified Gtk widget is destroyed Any additional parameters will be passed to the callback. :returns: a convenience function that you can call to remove the callback. """ global EVENT_MANAGER return EVENT_MANAGER.add_callback(function, evty, obj, args, kwargs)
def add_ui_callback(function, evty=None, obj=None, *args, **kwargs): """ Adds a callback to an event. The callback is guaranteed to always be called on the UI thread. You should ALWAYS specify one of the two options on what to listen for. While not forbidden to listen to all events, doing so will cause your callback to be called very frequently, and possibly may cause slowness within the player itself. :param function: the function to call when the event happens :type function: callable :param evty: the *type* or *name* of the event to listen for, eg `tracks_added`, `cover_changed`. Defaults to any event if not specified. :type evty: string :param obj: the object to listen to events from, e.g. `exaile.collection` or `xl.covers.MANAGER`. Defaults to any object if not specified. :type obj: object :param destroy_with: (keyword arg only) If specified, this event will be detached when the specified Gtk widget is destroyed Any additional parameters will be passed to the callback. :returns: a convenience function that you can call to remove the callback. """ global EVENT_MANAGER return EVENT_MANAGER.add_callback(function, evty, obj, args, kwargs, ui=True)
[docs]def remove_callback(function, evty=None, obj=None): """ Removes a callback. Can remove both ui and non-ui callbacks. The parameters passed should match those that were passed when adding the callback """ global EVENT_MANAGER EVENT_MANAGER.remove_callback(function, evty, obj)
class Event: """ Represents an Event """ __slots__ = ['type', 'object', 'data'] def __init__(self, evty, obj, data): """ evty: the 'type' or 'name' for this Event [string] obj: the object emitting the Event [object] data: some piece of data relevant to the Event [object] """ self.type = evty self.object = obj self.data = data class Callback: """ Represents a callback """ __slots__ = ['wfunction', 'time', 'args', 'kwargs'] def __init__(self, function, time, args, kwargs): """ @param function: the function to call @param time: the time this callback was added """ self.wfunction = _getWeakRef(function) self.time = time self.args = args self.kwargs = kwargs def __repr__(self): return '<Callback %s>' % self.wfunction() class _WeakMethod: """Represent a weak bound method, i.e. a method doesn't keep alive the object that it is bound to. It uses WeakRef which, used on its own, produces weak methods that are dead on creation, not very useful. Typically, you will use the getRef() function instead of using this class directly.""" def __init__(self, method, notifyDead=None): """ The method must be bound. notifyDead will be called when object that method is bound to dies. """ assert ismethod(method) if method.__self__ is None: raise ValueError("We need a bound method!") if notifyDead is None: self.objRef = weakref.ref(method.__self__) else: self.objRef = weakref.ref(method.__self__, notifyDead) self.fun = method.__func__ def __call__(self): objref = self.objRef() if objref is not None: return types.MethodType(self.fun, objref) def __eq__(self, method2): if not isinstance(method2, _WeakMethod): return False return ( self.fun is method2.fun and self.objRef() is method2.objRef() and self.objRef() is not None ) def __hash__(self): return hash(self.fun) def __repr__(self): dead = '' if self.objRef() is None: dead = '; DEAD' obj = '<%s at %s%s>' % (self.__class__, id(self), dead) return obj def refs(self, weakRef): """Return true if we are storing same object referred to by weakRef.""" return self.objRef == weakRef def _getWeakRef(obj, notifyDead=None): """ Get a weak reference to obj. If obj is a bound method, a _WeakMethod object, that behaves like a WeakRef, is returned, if it is anything else a WeakRef is returned. If obj is an unbound method, a ValueError will be raised. """ if ismethod(obj): createRef = _WeakMethod else: createRef = weakref.ref if notifyDead is None: return createRef(obj) else: return createRef(obj, notifyDead) class EventManager: """ Manages all Events """ def __init__(self, use_logger=False, logger_filter=None, verbose=False): # sacrifice space for speed in emit self.all_callbacks = {} self.callbacks = {} self.ui_callbacks = {} self.use_logger = use_logger self.use_verbose_logger = verbose self.logger_filter = logger_filter # RLock is needed so that event callbacks can themselves send # synchronous events and add or remove callbacks self.lock = threading.RLock() self.pending_ui = [] self.pending_ui_lock = threading.Lock() def emit(self, event): """ Emits an Event, calling any registered callbacks. event: the Event to emit [Event] """ emit_logmsg = self.use_logger and ( not self.logger_filter or re.search(self.logger_filter, event.type) ) emit_verbose = emit_logmsg and self.use_verbose_logger global _UiThread is_ui_thread = threading.current_thread() == _UiThread # note: a majority of the calls to emit are made on the # UI thread if is_ui_thread: self._emit(event, self.all_callbacks, emit_logmsg, emit_verbose) else: # Don't issue the log message twice with self.pending_ui_lock: do_emit = not self.pending_ui self.pending_ui.append( (event, self.ui_callbacks, emit_logmsg, emit_verbose) ) if do_emit: GLib.idle_add(self._emit_pending) self._emit(event, self.callbacks, False, emit_verbose) def _emit_pending(self): with self.pending_ui_lock: events = self.pending_ui self.pending_ui = [] for event in events: self._emit(*event) def _emit(self, event, exc_callbacks, emit_logmsg, emit_verbose): # Accumulate in this set to ensure callbacks only get called once callbacks = set() with self.lock: for tcall in [_NONE, event.type]: tcb = exc_callbacks.get(tcall) if tcb is not None: for ocall in [_NONE, event.object]: ocb = tcb.get(ocall) if ocb is not None: callbacks.update(ocb) # However, do not actually call the callbacks from within the lock # -> Otherwise non-ui threads could accidentally block the UI if # they decide to run for too long for cb in callbacks: try: fn = cb.wfunction() if fn is None: # Remove callbacks that have been garbage collected.. but # really, should be using remove_callback to clean up after # your event handler with self.lock: try: exc_callbacks[event.type][event.object].remove(cb) except (KeyError, ValueError): pass else: if emit_verbose: logger.debug( "Attempting to call " "%(function)s in response " "to %(event)s." % {'function': fn, 'event': event.type} ) fn.__call__( event.type, event.object, event.data, *cb.args, **cb.kwargs ) fn = None except Exception: # something went wrong inside the function we're calling logger.exception("Event callback exception caught!") if emit_logmsg: logger.debug( "Sent '%s' event from %r with data %r", event.type, event.object, event.data, ) def emit_async(self, event): """ Same as emit(), but does not block. """ GLib.idle_add(self.emit, event) def add_callback(self, function, evty, obj, args, kwargs, ui=False): """ Registers a callback. You should always specify at least one of event type or object. @param function: The function to call [function] @param evty: The 'type' or 'name' of event to listen for. Defaults to any. [string] @param obj: The object to listen to events from. Defaults to any. [string] Returns a convenience function that you can call to remove the callback. """ if ui: all_cbs = [self.ui_callbacks, self.all_callbacks] else: all_cbs = [self.callbacks, self.all_callbacks] destroy_with = kwargs.pop('destroy_with', None) if evty is None: evty = _NONE if obj is None: obj = _NONE with self.lock: cb = Callback(function, time.time(), args, kwargs) # add the specified categories if needed. for cbs in all_cbs: if evty not in cbs: cbs[evty] = weakref.WeakKeyDictionary() try: callbacks = cbs[evty][obj] except KeyError: callbacks = cbs[evty][obj] = [] # add the actual callback callbacks.append(cb) if self.use_logger: if ( not self.logger_filter or evty is _NONE or re.search(self.logger_filter, evty) ): logger.debug("Added callback %s for [%s, %s]" % (function, evty, obj)) if destroy_with is not None: destroy_with.connect( 'destroy', lambda w: self.remove_callback(function, evty, obj) ) return lambda: self.remove_callback(function, evty, obj) def remove_callback(self, function, evty=None, obj=None): """ Unsets a callback The parameters must match those given when the callback was registered. (minus any additional args) """ if evty is None: evty = _NONE if obj is None: obj = _NONE with self.lock: for cbs in [self.callbacks, self.all_callbacks, self.ui_callbacks]: remove = [] try: callbacks = cbs[evty][obj] for cb in callbacks: if cb.wfunction() == function: remove.append(cb) except KeyError: continue except TypeError: continue for cb in remove: callbacks.remove(cb) if len(callbacks) == 0: del cbs[evty][obj] if len(cbs[evty]) == 0: del cbs[evty] if self.use_logger: if ( not self.logger_filter or evty is _NONE or re.search(self.logger_filter, evty) ): logger.debug("Removed callback %s for [%s, %s]" % (function, evty, obj)) EVENT_MANAGER = EventManager() # vim: et sts=4 sw=4