Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# Copyright 2017, Google LLC
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7# http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
15"""Abstract and helper bases for Future implementations."""
17import abc
18import concurrent.futures
20from google.api_core import exceptions
21from google.api_core import retry as retries
22from google.api_core.future import _helpers
23from google.api_core.future import base
26class _OperationNotComplete(Exception):
27 """Private exception used for polling via retry."""
29 pass
32# DEPRECATED as it conflates RPC retry and polling concepts into one.
33# Use POLLING_PREDICATE instead to configure polling.
34RETRY_PREDICATE = retries.if_exception_type(
35 _OperationNotComplete,
36 exceptions.TooManyRequests,
37 exceptions.InternalServerError,
38 exceptions.BadGateway,
39 exceptions.ServiceUnavailable,
40)
42# DEPRECATED: use DEFAULT_POLLING to configure LRO polling logic. Construct
43# Retry object using its default values as a baseline for any custom retry logic
44# (not to be confused with polling logic).
45DEFAULT_RETRY = retries.Retry(predicate=RETRY_PREDICATE)
47# POLLING_PREDICATE is supposed to poll only on _OperationNotComplete.
48# Any RPC-specific errors (like ServiceUnavailable) will be handled
49# by retry logic (not to be confused with polling logic) which is triggered for
50# every polling RPC independently of polling logic but within its context.
51POLLING_PREDICATE = retries.if_exception_type(
52 _OperationNotComplete,
53)
55# Default polling configuration
56DEFAULT_POLLING = retries.Retry(
57 predicate=POLLING_PREDICATE,
58 initial=1.0, # seconds
59 maximum=20.0, # seconds
60 multiplier=1.5,
61 timeout=900, # seconds
62)
65class PollingFuture(base.Future):
66 """A Future that needs to poll some service to check its status.
68 The :meth:`done` method should be implemented by subclasses. The polling
69 behavior will repeatedly call ``done`` until it returns True.
71 The actual polling logic is encapsulated in :meth:`result` method. See
72 documentation for that method for details on how polling works.
74 .. note::
76 Privacy here is intended to prevent the final class from
77 overexposing, not to prevent subclasses from accessing methods.
79 Args:
80 polling (google.api_core.retry.Retry): The configuration used for polling.
81 This parameter controls how often :meth:`done` is polled. If the
82 ``timeout`` argument is specified in :meth:`result` method it will
83 override the ``polling.timeout`` property.
84 retry (google.api_core.retry.Retry): DEPRECATED use ``polling`` instead.
85 If set, it will override ``polling`` parameter for backward
86 compatibility.
87 """
89 _DEFAULT_VALUE = object()
91 def __init__(self, polling=DEFAULT_POLLING, **kwargs):
92 super(PollingFuture, self).__init__()
93 self._polling = kwargs.get("retry", polling)
94 self._result = None
95 self._exception = None
96 self._result_set = False
97 """bool: Set to True when the result has been set via set_result or
98 set_exception."""
99 self._polling_thread = None
100 self._done_callbacks = []
102 @abc.abstractmethod
103 def done(self, retry=None):
104 """Checks to see if the operation is complete.
106 Args:
107 retry (google.api_core.retry.Retry): (Optional) How to retry the
108 polling RPC (to not be confused with polling configuration. See
109 the documentation for :meth:`result` for details).
111 Returns:
112 bool: True if the operation is complete, False otherwise.
113 """
114 # pylint: disable=redundant-returns-doc, missing-raises-doc
115 raise NotImplementedError()
117 def _done_or_raise(self, retry=None):
118 """Check if the future is done and raise if it's not."""
119 if not self.done(retry=retry):
120 raise _OperationNotComplete()
122 def running(self):
123 """True if the operation is currently running."""
124 return not self.done()
126 def _blocking_poll(self, timeout=_DEFAULT_VALUE, retry=None, polling=None):
127 """Poll and wait for the Future to be resolved."""
129 if self._result_set:
130 return
132 polling = polling or self._polling
133 if timeout is not PollingFuture._DEFAULT_VALUE:
134 polling = polling.with_timeout(timeout)
136 try:
137 polling(self._done_or_raise)(retry=retry)
138 except exceptions.RetryError:
139 raise concurrent.futures.TimeoutError(
140 f"Operation did not complete within the designated timeout of "
141 f"{polling.timeout} seconds."
142 )
144 def result(self, timeout=_DEFAULT_VALUE, retry=None, polling=None):
145 """Get the result of the operation.
147 This method will poll for operation status periodically, blocking if
148 necessary. If you just want to make sure that this method does not block
149 for more than X seconds and you do not care about the nitty-gritty of
150 how this method operates, just call it with ``result(timeout=X)``. The
151 other parameters are for advanced use only.
153 Every call to this method is controlled by the following three
154 parameters, each of which has a specific, distinct role, even though all three
155 may look very similar: ``timeout``, ``retry`` and ``polling``. In most
156 cases users do not need to specify any custom values for any of these
157 parameters and may simply rely on default ones instead.
159 If you choose to specify custom parameters, please make sure you've
160 read the documentation below carefully.
162 First, please check :class:`google.api_core.retry.Retry`
163 class documentation for the proper definition of timeout and deadline
164 terms and for the definition the three different types of timeouts.
165 This class operates in terms of Retry Timeout and Polling Timeout. It
166 does not let customizing RPC timeout and the user is expected to rely on
167 default behavior for it.
169 The roles of each argument of this method are as follows:
171 ``timeout`` (int): (Optional) The Polling Timeout as defined in
172 :class:`google.api_core.retry.Retry`. If the operation does not complete
173 within this timeout an exception will be thrown. This parameter affects
174 neither Retry Timeout nor RPC Timeout.
176 ``retry`` (google.api_core.retry.Retry): (Optional) How to retry the
177 polling RPC. The ``retry.timeout`` property of this parameter is the
178 Retry Timeout as defined in :class:`google.api_core.retry.Retry`.
179 This parameter defines ONLY how the polling RPC call is retried
180 (i.e. what to do if the RPC we used for polling returned an error). It
181 does NOT define how the polling is done (i.e. how frequently and for
182 how long to call the polling RPC); use the ``polling`` parameter for that.
183 If a polling RPC throws and error and retrying it fails, the whole
184 future fails with the corresponding exception. If you want to tune which
185 server response error codes are not fatal for operation polling, use this
186 parameter to control that (``retry.predicate`` in particular).
188 ``polling`` (google.api_core.retry.Retry): (Optional) How often and
189 for how long to call the polling RPC periodically (i.e. what to do if
190 a polling rpc returned successfully but its returned result indicates
191 that the long running operation is not completed yet, so we need to
192 check it again at some point in future). This parameter does NOT define
193 how to retry each individual polling RPC in case of an error; use the
194 ``retry`` parameter for that. The ``polling.timeout`` of this parameter
195 is Polling Timeout as defined in as defined in
196 :class:`google.api_core.retry.Retry`.
198 For each of the arguments, there are also default values in place, which
199 will be used if a user does not specify their own. The default values
200 for the three parameters are not to be confused with the default values
201 for the corresponding arguments in this method (those serve as "not set"
202 markers for the resolution logic).
204 If ``timeout`` is provided (i.e.``timeout is not _DEFAULT VALUE``; note
205 the ``None`` value means "infinite timeout"), it will be used to control
206 the actual Polling Timeout. Otherwise, the ``polling.timeout`` value
207 will be used instead (see below for how the ``polling`` config itself
208 gets resolved). In other words, this parameter effectively overrides
209 the ``polling.timeout`` value if specified. This is so to preserve
210 backward compatibility.
212 If ``retry`` is provided (i.e. ``retry is not None``) it will be used to
213 control retry behavior for the polling RPC and the ``retry.timeout``
214 will determine the Retry Timeout. If not provided, the
215 polling RPC will be called with whichever default retry config was
216 specified for the polling RPC at the moment of the construction of the
217 polling RPC's client. For example, if the polling RPC is
218 ``operations_client.get_operation()``, the ``retry`` parameter will be
219 controlling its retry behavior (not polling behavior) and, if not
220 specified, that specific method (``operations_client.get_operation()``)
221 will be retried according to the default retry config provided during
222 creation of ``operations_client`` client instead. This argument exists
223 mainly for backward compatibility; users are very unlikely to ever need
224 to set this parameter explicitly.
226 If ``polling`` is provided (i.e. ``polling is not None``), it will be used
227 to control the overall polling behavior and ``polling.timeout`` will
228 control Polling Timeout unless it is overridden by ``timeout`` parameter
229 as described above. If not provided, the``polling`` parameter specified
230 during construction of this future (the ``polling`` argument in the
231 constructor) will be used instead. Note: since the ``timeout`` argument may
232 override ``polling.timeout`` value, this parameter should be viewed as
233 coupled with the ``timeout`` parameter as described above.
235 Args:
236 timeout (int): (Optional) How long (in seconds) to wait for the
237 operation to complete. If None, wait indefinitely.
238 retry (google.api_core.retry.Retry): (Optional) How to retry the
239 polling RPC. This defines ONLY how the polling RPC call is
240 retried (i.e. what to do if the RPC we used for polling returned
241 an error). It does NOT define how the polling is done (i.e. how
242 frequently and for how long to call the polling RPC).
243 polling (google.api_core.retry.Retry): (Optional) How often and
244 for how long to call polling RPC periodically. This parameter
245 does NOT define how to retry each individual polling RPC call
246 (use the ``retry`` parameter for that).
248 Returns:
249 google.protobuf.Message: The Operation's result.
251 Raises:
252 google.api_core.GoogleAPICallError: If the operation errors or if
253 the timeout is reached before the operation completes.
254 """
256 self._blocking_poll(timeout=timeout, retry=retry, polling=polling)
258 if self._exception is not None:
259 # pylint: disable=raising-bad-type
260 # Pylint doesn't recognize that this is valid in this case.
261 raise self._exception
263 return self._result
265 def exception(self, timeout=_DEFAULT_VALUE):
266 """Get the exception from the operation, blocking if necessary.
268 See the documentation for the :meth:`result` method for details on how
269 this method operates, as both ``result`` and this method rely on the
270 exact same polling logic. The only difference is that this method does
271 not accept ``retry`` and ``polling`` arguments but relies on the default ones
272 instead.
274 Args:
275 timeout (int): How long to wait for the operation to complete.
276 If None, wait indefinitely.
278 Returns:
279 Optional[google.api_core.GoogleAPICallError]: The operation's
280 error.
281 """
282 self._blocking_poll(timeout=timeout)
283 return self._exception
285 def add_done_callback(self, fn):
286 """Add a callback to be executed when the operation is complete.
288 If the operation is not already complete, this will start a helper
289 thread to poll for the status of the operation in the background.
291 Args:
292 fn (Callable[Future]): The callback to execute when the operation
293 is complete.
294 """
295 if self._result_set:
296 _helpers.safe_invoke_callback(fn, self)
297 return
299 self._done_callbacks.append(fn)
301 if self._polling_thread is None:
302 # The polling thread will exit on its own as soon as the operation
303 # is done.
304 self._polling_thread = _helpers.start_daemon_thread(
305 target=self._blocking_poll
306 )
308 def _invoke_callbacks(self, *args, **kwargs):
309 """Invoke all done callbacks."""
310 for callback in self._done_callbacks:
311 _helpers.safe_invoke_callback(callback, *args, **kwargs)
313 def set_result(self, result):
314 """Set the Future's result."""
315 self._result = result
316 self._result_set = True
317 self._invoke_callbacks(self)
319 def set_exception(self, exception):
320 """Set the Future's exception."""
321 self._exception = exception
322 self._result_set = True
323 self._invoke_callbacks(self)