| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203 |
- """Kazoo Interfaces
- .. versionchanged:: 1.4
- The classes in this module used to be interface declarations based on
- `zope.interface.Interface`. They were converted to normal classes and
- now serve as documentation only.
- """
- # public API
- class IHandler(object):
- """A Callback Handler for Zookeeper completion and watch callbacks.
- This object must implement several methods responsible for
- determining how completion / watch callbacks are handled as well as
- the method for calling :class:`IAsyncResult` callback functions.
- These functions are used to abstract differences between a Python
- threading environment and asynchronous single-threaded environments
- like gevent. The minimum functionality needed for Kazoo to handle
- these differences is encompassed in this interface.
- The Handler should document how callbacks are called for:
- * Zookeeper completion events
- * Zookeeper watch events
- .. attribute:: name
- Human readable name of the Handler interface.
- .. attribute:: timeout_exception
- Exception class that should be thrown and captured if a
- result is not available within the given time.
- .. attribute:: sleep_func
- Appropriate sleep function that can be called with a single
- argument and sleep.
- """
- def start(self):
- """Start the handler, used for setting up the handler."""
- def stop(self):
- """Stop the handler. Should block until the handler is safely
- stopped."""
- def select(self):
- """A select method that implements Python's select.select
- API"""
- def socket(self):
- """A socket method that implements Python's socket.socket
- API"""
- def create_connection(self):
- """A socket method that implements Python's
- socket.create_connection API"""
- def event_object(self):
- """Return an appropriate object that implements Python's
- threading.Event API"""
- def lock_object(self):
- """Return an appropriate object that implements Python's
- threading.Lock API"""
- def rlock_object(self):
- """Return an appropriate object that implements Python's
- threading.RLock API"""
- def async_result(self):
- """Return an instance that conforms to the
- :class:`~IAsyncResult` interface appropriate for this
- handler"""
- def spawn(self, func, *args, **kwargs):
- """Spawn a function to run asynchronously
- :param args: args to call the function with.
- :param kwargs: keyword args to call the function with.
- This method should return immediately and execute the function
- with the provided args and kwargs in an asynchronous manner.
- """
- def dispatch_callback(self, callback):
- """Dispatch to the callback object
- :param callback: A :class:`~kazoo.protocol.states.Callback`
- object to be called.
- """
- class IAsyncResult(object):
- """An Async Result object that can be queried for a value that has
- been set asynchronously.
- This object is modeled on the ``gevent`` AsyncResult object.
- The implementation must account for the fact that the :meth:`set`
- and :meth:`set_exception` methods will be called from within the
- Zookeeper thread which may require extra care under asynchronous
- environments.
- .. attribute:: value
- Holds the value passed to :meth:`set` if :meth:`set` was
- called. Otherwise `None`.
- .. attribute:: exception
- Holds the exception instance passed to :meth:`set_exception`
- if :meth:`set_exception` was called. Otherwise `None`.
- """
- def ready(self):
- """Return `True` if and only if it holds a value or an
- exception"""
- def successful(self):
- """Return `True` if and only if it is ready and holds a
- value"""
- def set(self, value=None):
- """Store the value. Wake up the waiters.
- :param value: Value to store as the result.
- Any waiters blocking on :meth:`get` or :meth:`wait` are woken
- up. Sequential calls to :meth:`wait` and :meth:`get` will not
- block at all."""
- def set_exception(self, exception):
- """Store the exception. Wake up the waiters.
- :param exception: Exception to raise when fetching the value.
- Any waiters blocking on :meth:`get` or :meth:`wait` are woken
- up. Sequential calls to :meth:`wait` and :meth:`get` will not
- block at all."""
- def get(self, block=True, timeout=None):
- """Return the stored value or raise the exception
- :param block: Whether this method should block or return
- immediately.
- :type block: bool
- :param timeout: How long to wait for a value when `block` is
- `True`.
- :type timeout: float
- If this instance already holds a value / an exception, return /
- raise it immediately. Otherwise, block until :meth:`set` or
- :meth:`set_exception` has been called or until the optional
- timeout occurs."""
- def get_nowait(self):
- """Return the value or raise the exception without blocking.
- If nothing is available, raise the Timeout exception class on
- the associated :class:`IHandler` interface."""
- def wait(self, timeout=None):
- """Block until the instance is ready.
- :param timeout: How long to wait for a value when `block` is
- `True`.
- :type timeout: float
- If this instance already holds a value / an exception, return /
- raise it immediately. Otherwise, block until :meth:`set` or
- :meth:`set_exception` has been called or until the optional
- timeout occurs."""
- def rawlink(self, callback):
- """Register a callback to call when a value or an exception is
- set
- :param callback:
- A callback function to call after :meth:`set` or
- :meth:`set_exception` has been called. This function will
- be passed a single argument, this instance.
- :type callback: func
- """
- def unlink(self, callback):
- """Remove the callback set by :meth:`rawlink`
- :param callback: A callback function to remove.
- :type callback: func
- """
|