You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
|
|
"""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
"""
|
