# -*- coding: utf-8 -*-
# Copyright (C) 2014 Yahoo! Inc. All Rights Reserved.
#
# 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.
import collections
import contextlib
import copy
import logging
from oslo_utils import reflection
LOG = logging.getLogger(__name__)
[docs]
class Listener(object):
"""Immutable helper that represents a notification listener/target."""
def __init__(self, callback, args=None, kwargs=None, details_filter=None):
"""Initialize members
:param callback: callback function
:param details_filter: a callback that will be called before the
actual callback that can be used to discard
the event (thus avoiding the invocation of
the actual callback)
:param args: non-keyworded arguments
:type args: list/iterable/tuple
:param kwargs: key-value pair arguments
:type kwargs: dictionary
"""
self._callback = callback
self._details_filter = details_filter
if not args:
self._args = ()
else:
if not isinstance(args, tuple):
self._args = tuple(args)
else:
self._args = args
if not kwargs:
self._kwargs = {}
else:
self._kwargs = kwargs.copy()
@property
def callback(self):
"""Callback (can not be none) to call with event + details."""
return self._callback
@property
def details_filter(self):
"""Callback (may be none) to call to discard events + details."""
return self._details_filter
@property
def kwargs(self):
"""Dictionary of keyword arguments to use in future calls."""
return self._kwargs.copy()
@property
def args(self):
"""Tuple of positional arguments to use in future calls."""
return self._args
[docs]
def __call__(self, event_type, details):
"""Activate the target callback with the given event + details.
NOTE(harlowja): if a details filter callback exists and it returns
a falsey value when called with the provided ``details``, then the
target callback will **not** be called.
"""
if self._details_filter is not None:
if not self._details_filter(details):
return
kwargs = self._kwargs.copy()
kwargs['details'] = details
self._callback(event_type, *self._args, **kwargs)
def __repr__(self):
repr_msg = "%s object at 0x%x calling into '%r'" % (
reflection.get_class_name(self, fully_qualified=False),
id(self), self._callback)
if self._details_filter is not None:
repr_msg += " using details filter '%r'" % self._details_filter
return "<%s>" % repr_msg
[docs]
def is_equivalent(self, callback, details_filter=None):
"""Check if the callback is same
:param callback: callback used for comparison
:param details_filter: callback used for comparison
:returns: false if not the same callback, otherwise true
:rtype: boolean
"""
if not reflection.is_same_callback(self._callback, callback):
return False
if details_filter is not None:
if self._details_filter is None:
return False
else:
return reflection.is_same_callback(self._details_filter,
details_filter)
else:
return self._details_filter is None
def __eq__(self, other):
if isinstance(other, Listener):
return self.is_equivalent(other._callback,
details_filter=other._details_filter)
else:
return NotImplemented
def __ne__(self, other):
return not self.__eq__(other)
[docs]
class Notifier(object):
"""A notification (`pub/sub`_ *like*) helper class.
It is intended to be used to subscribe to notifications of events
occurring as well as allow a entity to post said notifications to any
associated subscribers without having either entity care about how this
notification occurs.
**Not** thread-safe when a single notifier is mutated at the same
time by multiple threads. For example having multiple threads call
into :py:meth:`.register` or :py:meth:`.reset` at the same time could
potentially end badly. It is thread-safe when
only :py:meth:`.notify` calls or other read-only actions (like calling
into :py:meth:`.is_registered`) are occurring at the same time.
.. _pub/sub: http://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern
"""
#: Keys that can *not* be used in callbacks arguments
RESERVED_KEYS = ('details',)
#: Kleene star constant that is used to receive all notifications
ANY = '*'
#: Events which can *not* be used to trigger notifications
_DISALLOWED_NOTIFICATION_EVENTS = set([ANY])
def __init__(self):
self._topics = collections.defaultdict(list)
def __len__(self):
"""Returns how many callbacks are registered.
:returns: count of how many callbacks are registered
:rtype: number
"""
count = 0
for (_event_type, listeners) in self._topics.items():
count += len(listeners)
return count
[docs]
def is_registered(self, event_type, callback, details_filter=None):
"""Check if a callback is registered.
:returns: checks if the callback is registered
:rtype: boolean
"""
for listener in self._topics.get(event_type, []):
if listener.is_equivalent(callback, details_filter=details_filter):
return True
return False
[docs]
def reset(self):
"""Forget all previously registered callbacks."""
self._topics.clear()
[docs]
def notify(self, event_type, details):
"""Notify about event occurrence.
All callbacks registered to receive notifications about given
event type will be called. If the provided event type can not be
used to emit notifications (this is checked via
the :meth:`.can_be_registered` method) then it will silently be
dropped (notification failures are not allowed to cause or
raise exceptions).
:param event_type: event type that occurred
:param details: additional event details *dictionary* passed to
callback keyword argument with the same name
:type details: dictionary
"""
if not self.can_trigger_notification(event_type):
LOG.debug("Event type '%s' is not allowed to trigger"
" notifications", event_type)
return
listeners = list(self._topics.get(self.ANY, []))
listeners.extend(self._topics.get(event_type, []))
if not listeners:
return
if not details:
details = {}
for listener in listeners:
try:
listener(event_type, details.copy())
except Exception:
LOG.warning("Failure calling listener %s to notify about event"
" %s, details: %s", listener, event_type,
details, exc_info=True)
[docs]
def register(self, event_type, callback,
args=None, kwargs=None, details_filter=None):
"""Register a callback to be called when event of a given type occurs.
Callback will be called with provided ``args`` and ``kwargs`` and
when event type occurs (or on any event if ``event_type`` equals to
:attr:`.ANY`). It will also get additional keyword argument,
``details``, that will hold event details provided to the
:meth:`.notify` method (if a details filter callback is provided then
the target callback will *only* be triggered if the details filter
callback returns a truthy value).
:param event_type: event type input
:param callback: function callback to be registered.
:param args: non-keyworded arguments
:type args: list
:param kwargs: key-value pair arguments
:type kwargs: dictionary
"""
if not callable(callback):
raise ValueError("Event callback must be callable")
if details_filter is not None:
if not callable(details_filter):
raise ValueError("Details filter must be callable")
if not self.can_be_registered(event_type):
raise ValueError("Disallowed event type '%s' can not have a"
" callback registered" % event_type)
if self.is_registered(event_type, callback,
details_filter=details_filter):
raise ValueError("Event callback already registered with"
" equivalent details filter")
if kwargs:
for k in self.RESERVED_KEYS:
if k in kwargs:
raise KeyError("Reserved key '%s' not allowed in "
"kwargs" % k)
self._topics[event_type].append(
Listener(callback,
args=args, kwargs=kwargs,
details_filter=details_filter))
[docs]
def deregister(self, event_type, callback, details_filter=None):
"""Remove a single listener bound to event ``event_type``.
:param event_type: deregister listener bound to event_type
"""
if event_type not in self._topics:
return False
for i, listener in enumerate(self._topics.get(event_type, [])):
if listener.is_equivalent(callback, details_filter=details_filter):
self._topics[event_type].pop(i)
return True
return False
[docs]
def deregister_event(self, event_type):
"""Remove a group of listeners bound to event ``event_type``.
:param event_type: deregister listeners bound to event_type
"""
return len(self._topics.pop(event_type, []))
def copy(self):
c = copy.copy(self)
c._topics = collections.defaultdict(list)
for (event_type, listeners) in self._topics.items():
c._topics[event_type] = listeners[:]
return c
[docs]
def listeners_iter(self):
"""Return an iterator over the mapping of event => listeners bound.
NOTE(harlowja): Each listener in the yielded (event, listeners)
tuple is an instance of the :py:class:`~.Listener` type, which
itself wraps a provided callback (and its details filter
callback, if any).
"""
for event_type, listeners in self._topics.items():
if listeners:
yield (event_type, listeners)
[docs]
def can_be_registered(self, event_type):
"""Checks if the event can be registered/subscribed to."""
return True
[docs]
def can_trigger_notification(self, event_type):
"""Checks if the event can trigger a notification.
:param event_type: event that needs to be verified
:returns: whether the event can trigger a notification
:rtype: boolean
"""
if event_type in self._DISALLOWED_NOTIFICATION_EVENTS:
return False
else:
return True
[docs]
class RestrictedNotifier(Notifier):
"""A notification class that restricts events registered/triggered.
NOTE(harlowja): This class unlike :class:`.Notifier` restricts and
disallows registering callbacks for event types that are not declared
when constructing the notifier.
"""
def __init__(self, watchable_events, allow_any=True):
super(RestrictedNotifier, self).__init__()
self._watchable_events = frozenset(watchable_events)
self._allow_any = allow_any
[docs]
def events_iter(self):
"""Returns iterator of events that can be registered/subscribed to.
NOTE(harlowja): does not include back the ``ANY`` event type as that
meta-type is not a specific event but is a capture-all that does not
imply the same meaning as specific event types.
"""
for event_type in self._watchable_events:
yield event_type
[docs]
def can_be_registered(self, event_type):
"""Checks if the event can be registered/subscribed to.
:param event_type: event that needs to be verified
:returns: whether the event can be registered/subscribed to
:rtype: boolean
"""
return (event_type in self._watchable_events or
(event_type == self.ANY and self._allow_any))
[docs]
@contextlib.contextmanager
def register_deregister(notifier, event_type, callback=None,
args=None, kwargs=None, details_filter=None):
"""Context manager that registers a callback, then deregisters on exit.
NOTE(harlowja): if the callback is none, then this registers nothing, which
is different from the behavior of the ``register`` method
which will *not* accept none as it is not callable...
"""
if callback is None:
yield
else:
notifier.register(event_type, callback,
args=args, kwargs=kwargs,
details_filter=details_filter)
try:
yield
finally:
notifier.deregister(event_type, callback,
details_filter=details_filter)
