1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
"""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
"""
|
