| """license: Apache License 2.0, see LICENSE for more details.""" |
| """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 |
| |
| """ |
