Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 1 | """A Future class similar to the one in PEP 3148.""" |
| 2 | |
Yury Selivanov | 6370f34 | 2017-12-10 18:36:12 -0500 | [diff] [blame] | 3 | __all__ = ( |
| 4 | 'CancelledError', 'TimeoutError', 'InvalidStateError', |
| 5 | 'Future', 'wrap_future', 'isfuture', |
| 6 | ) |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 7 | |
Yury Selivanov | a0c1ba6 | 2016-10-28 12:52:37 -0400 | [diff] [blame] | 8 | import concurrent.futures |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 9 | import logging |
Victor Stinner | 4c3c699 | 2013-12-19 22:42:40 +0100 | [diff] [blame] | 10 | import sys |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 11 | |
Yury Selivanov | a0c1ba6 | 2016-10-28 12:52:37 -0400 | [diff] [blame] | 12 | from . import base_futures |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 13 | from . import events |
Andrew Svetlov | f74ef45 | 2017-12-15 07:04:38 +0200 | [diff] [blame^] | 14 | from . import format_helpers |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 15 | |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 16 | |
Yury Selivanov | a0c1ba6 | 2016-10-28 12:52:37 -0400 | [diff] [blame] | 17 | CancelledError = base_futures.CancelledError |
| 18 | InvalidStateError = base_futures.InvalidStateError |
| 19 | TimeoutError = base_futures.TimeoutError |
| 20 | isfuture = base_futures.isfuture |
| 21 | |
| 22 | |
| 23 | _PENDING = base_futures._PENDING |
| 24 | _CANCELLED = base_futures._CANCELLED |
| 25 | _FINISHED = base_futures._FINISHED |
| 26 | |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 27 | |
| 28 | STACK_DEBUG = logging.DEBUG - 1 # heavy-duty debugging |
| 29 | |
| 30 | |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 31 | class Future: |
| 32 | """This class is *almost* compatible with concurrent.futures.Future. |
| 33 | |
| 34 | Differences: |
| 35 | |
Antoine Pitrou | 22b1128 | 2017-11-07 17:03:28 +0100 | [diff] [blame] | 36 | - This class is not thread-safe. |
| 37 | |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 38 | - result() and exception() do not take a timeout argument and |
| 39 | raise an exception when the future isn't done yet. |
| 40 | |
| 41 | - Callbacks registered with add_done_callback() are always called |
Antoine Pitrou | 22b1128 | 2017-11-07 17:03:28 +0100 | [diff] [blame] | 42 | via the event loop's call_soon(). |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 43 | |
| 44 | - This class is not compatible with the wait() and as_completed() |
| 45 | methods in the concurrent.futures package. |
| 46 | |
| 47 | (In Python 3.4 or later we may be able to unify the implementations.) |
| 48 | """ |
| 49 | |
| 50 | # Class variables serving as defaults for instance variables. |
| 51 | _state = _PENDING |
| 52 | _result = None |
| 53 | _exception = None |
| 54 | _loop = None |
Victor Stinner | fe22e09 | 2014-12-04 23:00:13 +0100 | [diff] [blame] | 55 | _source_traceback = None |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 56 | |
Guido van Rossum | 1140a03 | 2016-09-09 12:54:54 -0700 | [diff] [blame] | 57 | # This field is used for a dual purpose: |
| 58 | # - Its presence is a marker to declare that a class implements |
| 59 | # the Future protocol (i.e. is intended to be duck-type compatible). |
| 60 | # The value must also be not-None, to enable a subclass to declare |
| 61 | # that it is not compatible by setting this to None. |
| 62 | # - It is set by __iter__() below so that Task._step() can tell |
Andrew Svetlov | 8874342 | 2017-12-11 17:35:49 +0200 | [diff] [blame] | 63 | # the difference between |
| 64 | # `await Future()` or`yield from Future()` (correct) vs. |
Guido van Rossum | 1140a03 | 2016-09-09 12:54:54 -0700 | [diff] [blame] | 65 | # `yield Future()` (incorrect). |
| 66 | _asyncio_future_blocking = False |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 67 | |
Victor Stinner | c16bace | 2017-11-28 00:35:33 +0100 | [diff] [blame] | 68 | _log_traceback = False |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 69 | |
| 70 | def __init__(self, *, loop=None): |
| 71 | """Initialize the future. |
| 72 | |
Martin Panter | c04fb56 | 2016-02-10 05:44:01 +0000 | [diff] [blame] | 73 | The optional event_loop argument allows explicitly setting the event |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 74 | loop object used by the future. If it's not provided, the future uses |
| 75 | the default event loop. |
| 76 | """ |
| 77 | if loop is None: |
| 78 | self._loop = events.get_event_loop() |
| 79 | else: |
| 80 | self._loop = loop |
| 81 | self._callbacks = [] |
Victor Stinner | 80f53aa | 2014-06-27 13:52:20 +0200 | [diff] [blame] | 82 | if self._loop.get_debug(): |
Andrew Svetlov | f74ef45 | 2017-12-15 07:04:38 +0200 | [diff] [blame^] | 83 | self._source_traceback = format_helpers.extract_stack( |
| 84 | sys._getframe(1)) |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 85 | |
Yury Selivanov | a0c1ba6 | 2016-10-28 12:52:37 -0400 | [diff] [blame] | 86 | _repr_info = base_futures._future_repr_info |
Victor Stinner | 313a980 | 2014-07-29 12:58:23 +0200 | [diff] [blame] | 87 | |
| 88 | def __repr__(self): |
Yury Selivanov | 6370f34 | 2017-12-10 18:36:12 -0500 | [diff] [blame] | 89 | return '<{} {}>'.format(self.__class__.__name__, |
| 90 | ' '.join(self._repr_info())) |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 91 | |
INADA Naoki | 3e2ad8e | 2017-04-25 10:57:18 +0900 | [diff] [blame] | 92 | def __del__(self): |
| 93 | if not self._log_traceback: |
| 94 | # set_exception() was not called, or result() or exception() |
| 95 | # has consumed the exception |
| 96 | return |
| 97 | exc = self._exception |
| 98 | context = { |
Yury Selivanov | 6370f34 | 2017-12-10 18:36:12 -0500 | [diff] [blame] | 99 | 'message': |
| 100 | f'{self.__class__.__name__} exception was never retrieved', |
INADA Naoki | 3e2ad8e | 2017-04-25 10:57:18 +0900 | [diff] [blame] | 101 | 'exception': exc, |
| 102 | 'future': self, |
| 103 | } |
| 104 | if self._source_traceback: |
| 105 | context['source_traceback'] = self._source_traceback |
| 106 | self._loop.call_exception_handler(context) |
Victor Stinner | 4c3c699 | 2013-12-19 22:42:40 +0100 | [diff] [blame] | 107 | |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 108 | def cancel(self): |
| 109 | """Cancel the future and schedule callbacks. |
| 110 | |
| 111 | If the future is already done or cancelled, return False. Otherwise, |
| 112 | change the future's state to cancelled, schedule the callbacks and |
| 113 | return True. |
| 114 | """ |
Yury Selivanov | 7ce1c6f | 2017-06-11 13:49:18 +0000 | [diff] [blame] | 115 | self._log_traceback = False |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 116 | if self._state != _PENDING: |
| 117 | return False |
| 118 | self._state = _CANCELLED |
Yury Selivanov | a0c1ba6 | 2016-10-28 12:52:37 -0400 | [diff] [blame] | 119 | self._schedule_callbacks() |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 120 | return True |
| 121 | |
Yury Selivanov | a0c1ba6 | 2016-10-28 12:52:37 -0400 | [diff] [blame] | 122 | def _schedule_callbacks(self): |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 123 | """Internal: Ask the event loop to call all callbacks. |
| 124 | |
| 125 | The callbacks are scheduled to be called as soon as possible. Also |
| 126 | clears the callback list. |
| 127 | """ |
| 128 | callbacks = self._callbacks[:] |
| 129 | if not callbacks: |
| 130 | return |
| 131 | |
| 132 | self._callbacks[:] = [] |
| 133 | for callback in callbacks: |
| 134 | self._loop.call_soon(callback, self) |
| 135 | |
| 136 | def cancelled(self): |
| 137 | """Return True if the future was cancelled.""" |
| 138 | return self._state == _CANCELLED |
| 139 | |
| 140 | # Don't implement running(); see http://bugs.python.org/issue18699 |
| 141 | |
| 142 | def done(self): |
| 143 | """Return True if the future is done. |
| 144 | |
| 145 | Done means either that a result / exception are available, or that the |
| 146 | future was cancelled. |
| 147 | """ |
| 148 | return self._state != _PENDING |
| 149 | |
| 150 | def result(self): |
| 151 | """Return the result this future represents. |
| 152 | |
| 153 | If the future has been cancelled, raises CancelledError. If the |
| 154 | future's result isn't yet available, raises InvalidStateError. If |
| 155 | the future is done and has an exception set, this exception is raised. |
| 156 | """ |
| 157 | if self._state == _CANCELLED: |
| 158 | raise CancelledError |
| 159 | if self._state != _FINISHED: |
| 160 | raise InvalidStateError('Result is not ready.') |
Victor Stinner | e40c078 | 2013-12-21 00:19:33 +0100 | [diff] [blame] | 161 | self._log_traceback = False |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 162 | if self._exception is not None: |
| 163 | raise self._exception |
| 164 | return self._result |
| 165 | |
| 166 | def exception(self): |
| 167 | """Return the exception that was set on this future. |
| 168 | |
| 169 | The exception (or None if no exception was set) is returned only if |
| 170 | the future is done. If the future has been cancelled, raises |
| 171 | CancelledError. If the future isn't done yet, raises |
| 172 | InvalidStateError. |
| 173 | """ |
| 174 | if self._state == _CANCELLED: |
| 175 | raise CancelledError |
| 176 | if self._state != _FINISHED: |
| 177 | raise InvalidStateError('Exception is not set.') |
Victor Stinner | e40c078 | 2013-12-21 00:19:33 +0100 | [diff] [blame] | 178 | self._log_traceback = False |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 179 | return self._exception |
| 180 | |
| 181 | def add_done_callback(self, fn): |
| 182 | """Add a callback to be run when the future becomes done. |
| 183 | |
| 184 | The callback is called with a single argument - the future object. If |
| 185 | the future is already done when this is called, the callback is |
| 186 | scheduled with call_soon. |
| 187 | """ |
| 188 | if self._state != _PENDING: |
| 189 | self._loop.call_soon(fn, self) |
| 190 | else: |
| 191 | self._callbacks.append(fn) |
| 192 | |
| 193 | # New method not in PEP 3148. |
| 194 | |
| 195 | def remove_done_callback(self, fn): |
| 196 | """Remove all instances of a callback from the "call when done" list. |
| 197 | |
| 198 | Returns the number of callbacks removed. |
| 199 | """ |
| 200 | filtered_callbacks = [f for f in self._callbacks if f != fn] |
| 201 | removed_count = len(self._callbacks) - len(filtered_callbacks) |
| 202 | if removed_count: |
| 203 | self._callbacks[:] = filtered_callbacks |
| 204 | return removed_count |
| 205 | |
| 206 | # So-called internal methods (note: no set_running_or_notify_cancel()). |
| 207 | |
| 208 | def set_result(self, result): |
| 209 | """Mark the future done and set its result. |
| 210 | |
| 211 | If the future is already done when this method is called, raises |
| 212 | InvalidStateError. |
| 213 | """ |
| 214 | if self._state != _PENDING: |
| 215 | raise InvalidStateError('{}: {!r}'.format(self._state, self)) |
| 216 | self._result = result |
| 217 | self._state = _FINISHED |
Yury Selivanov | a0c1ba6 | 2016-10-28 12:52:37 -0400 | [diff] [blame] | 218 | self._schedule_callbacks() |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 219 | |
| 220 | def set_exception(self, exception): |
| 221 | """Mark the future done and set an exception. |
| 222 | |
| 223 | If the future is already done when this method is called, raises |
| 224 | InvalidStateError. |
| 225 | """ |
| 226 | if self._state != _PENDING: |
| 227 | raise InvalidStateError('{}: {!r}'.format(self._state, self)) |
Victor Stinner | 9572898 | 2014-01-30 16:01:54 -0800 | [diff] [blame] | 228 | if isinstance(exception, type): |
| 229 | exception = exception() |
Yury Selivanov | 1bd0307 | 2016-03-02 11:03:28 -0500 | [diff] [blame] | 230 | if type(exception) is StopIteration: |
| 231 | raise TypeError("StopIteration interacts badly with generators " |
| 232 | "and cannot be raised into a Future") |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 233 | self._exception = exception |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 234 | self._state = _FINISHED |
Yury Selivanov | a0c1ba6 | 2016-10-28 12:52:37 -0400 | [diff] [blame] | 235 | self._schedule_callbacks() |
INADA Naoki | 3e2ad8e | 2017-04-25 10:57:18 +0900 | [diff] [blame] | 236 | self._log_traceback = True |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 237 | |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 238 | def __iter__(self): |
| 239 | if not self.done(): |
Guido van Rossum | 1140a03 | 2016-09-09 12:54:54 -0700 | [diff] [blame] | 240 | self._asyncio_future_blocking = True |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 241 | yield self # This tells Task to wait for completion. |
Andrew Svetlov | 8874342 | 2017-12-11 17:35:49 +0200 | [diff] [blame] | 242 | assert self.done(), "await wasn't used with future" |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 243 | return self.result() # May raise too. |
| 244 | |
Yury Selivanov | 6370f34 | 2017-12-10 18:36:12 -0500 | [diff] [blame] | 245 | __await__ = __iter__ # make compatible with 'await' expression |
Yury Selivanov | 1af2bf7 | 2015-05-11 22:27:25 -0400 | [diff] [blame] | 246 | |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 247 | |
Yury Selivanov | 01c521b | 2016-10-23 22:34:35 -0400 | [diff] [blame] | 248 | # Needed for testing purposes. |
| 249 | _PyFuture = Future |
| 250 | |
| 251 | |
Yury Selivanov | 5d7e3b6 | 2015-11-17 12:19:41 -0500 | [diff] [blame] | 252 | def _set_result_unless_cancelled(fut, result): |
| 253 | """Helper setting the result only if the future was not cancelled.""" |
| 254 | if fut.cancelled(): |
| 255 | return |
| 256 | fut.set_result(result) |
| 257 | |
| 258 | |
Guido van Rossum | 841d9ee | 2015-10-03 08:31:42 -0700 | [diff] [blame] | 259 | def _set_concurrent_future_state(concurrent, source): |
| 260 | """Copy state from a future to a concurrent.futures.Future.""" |
| 261 | assert source.done() |
| 262 | if source.cancelled(): |
| 263 | concurrent.cancel() |
| 264 | if not concurrent.set_running_or_notify_cancel(): |
| 265 | return |
| 266 | exception = source.exception() |
| 267 | if exception is not None: |
| 268 | concurrent.set_exception(exception) |
| 269 | else: |
| 270 | result = source.result() |
| 271 | concurrent.set_result(result) |
| 272 | |
| 273 | |
Yury Selivanov | 5d7e3b6 | 2015-11-17 12:19:41 -0500 | [diff] [blame] | 274 | def _copy_future_state(source, dest): |
| 275 | """Internal helper to copy state from another Future. |
| 276 | |
| 277 | The other Future may be a concurrent.futures.Future. |
| 278 | """ |
| 279 | assert source.done() |
| 280 | if dest.cancelled(): |
| 281 | return |
| 282 | assert not dest.done() |
| 283 | if source.cancelled(): |
| 284 | dest.cancel() |
| 285 | else: |
| 286 | exception = source.exception() |
| 287 | if exception is not None: |
| 288 | dest.set_exception(exception) |
| 289 | else: |
| 290 | result = source.result() |
| 291 | dest.set_result(result) |
| 292 | |
| 293 | |
Guido van Rossum | 841d9ee | 2015-10-03 08:31:42 -0700 | [diff] [blame] | 294 | def _chain_future(source, destination): |
| 295 | """Chain two futures so that when one completes, so does the other. |
| 296 | |
| 297 | The result (or exception) of source will be copied to destination. |
| 298 | If destination is cancelled, source gets cancelled too. |
| 299 | Compatible with both asyncio.Future and concurrent.futures.Future. |
| 300 | """ |
Guido van Rossum | 7b3b3dc | 2016-09-09 14:26:31 -0700 | [diff] [blame] | 301 | if not isfuture(source) and not isinstance(source, |
| 302 | concurrent.futures.Future): |
Guido van Rossum | 841d9ee | 2015-10-03 08:31:42 -0700 | [diff] [blame] | 303 | raise TypeError('A future is required for source argument') |
Guido van Rossum | 7b3b3dc | 2016-09-09 14:26:31 -0700 | [diff] [blame] | 304 | if not isfuture(destination) and not isinstance(destination, |
| 305 | concurrent.futures.Future): |
Guido van Rossum | 841d9ee | 2015-10-03 08:31:42 -0700 | [diff] [blame] | 306 | raise TypeError('A future is required for destination argument') |
Guido van Rossum | 7b3b3dc | 2016-09-09 14:26:31 -0700 | [diff] [blame] | 307 | source_loop = source._loop if isfuture(source) else None |
| 308 | dest_loop = destination._loop if isfuture(destination) else None |
Guido van Rossum | 841d9ee | 2015-10-03 08:31:42 -0700 | [diff] [blame] | 309 | |
| 310 | def _set_state(future, other): |
Guido van Rossum | 7b3b3dc | 2016-09-09 14:26:31 -0700 | [diff] [blame] | 311 | if isfuture(future): |
Yury Selivanov | 5d7e3b6 | 2015-11-17 12:19:41 -0500 | [diff] [blame] | 312 | _copy_future_state(other, future) |
Guido van Rossum | 841d9ee | 2015-10-03 08:31:42 -0700 | [diff] [blame] | 313 | else: |
| 314 | _set_concurrent_future_state(future, other) |
| 315 | |
| 316 | def _call_check_cancel(destination): |
| 317 | if destination.cancelled(): |
| 318 | if source_loop is None or source_loop is dest_loop: |
| 319 | source.cancel() |
| 320 | else: |
| 321 | source_loop.call_soon_threadsafe(source.cancel) |
| 322 | |
| 323 | def _call_set_state(source): |
| 324 | if dest_loop is None or dest_loop is source_loop: |
| 325 | _set_state(destination, source) |
| 326 | else: |
| 327 | dest_loop.call_soon_threadsafe(_set_state, destination, source) |
| 328 | |
| 329 | destination.add_done_callback(_call_check_cancel) |
| 330 | source.add_done_callback(_call_set_state) |
| 331 | |
| 332 | |
| 333 | def wrap_future(future, *, loop=None): |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 334 | """Wrap concurrent.futures.Future object.""" |
Guido van Rossum | 7b3b3dc | 2016-09-09 14:26:31 -0700 | [diff] [blame] | 335 | if isfuture(future): |
Guido van Rossum | 841d9ee | 2015-10-03 08:31:42 -0700 | [diff] [blame] | 336 | return future |
| 337 | assert isinstance(future, concurrent.futures.Future), \ |
Yury Selivanov | 6370f34 | 2017-12-10 18:36:12 -0500 | [diff] [blame] | 338 | f'concurrent.futures.Future is expected, got {future!r}' |
Yury Selivanov | 7661db6 | 2016-05-16 15:38:39 -0400 | [diff] [blame] | 339 | if loop is None: |
| 340 | loop = events.get_event_loop() |
| 341 | new_future = loop.create_future() |
Guido van Rossum | 841d9ee | 2015-10-03 08:31:42 -0700 | [diff] [blame] | 342 | _chain_future(future, new_future) |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 343 | return new_future |
INADA Naoki | c411a7d | 2016-10-18 11:48:14 +0900 | [diff] [blame] | 344 | |
| 345 | |
| 346 | try: |
| 347 | import _asyncio |
| 348 | except ImportError: |
| 349 | pass |
| 350 | else: |
Yury Selivanov | 01c521b | 2016-10-23 22:34:35 -0400 | [diff] [blame] | 351 | # _CFuture is needed for tests. |
| 352 | Future = _CFuture = _asyncio.Future |