1# Copyright 2015 gRPC authors.
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.
14"""A Future interface.
15
16Python doesn't have a Future interface in its standard library. In the absence
17of such a standard, three separate, incompatible implementations
18(concurrent.futures.Future, ndb.Future, and asyncio.Future) have appeared. This
19interface attempts to be as compatible as possible with
20concurrent.futures.Future. From ndb.Future it adopts a traceback-object accessor
21method.
22
23Unlike the concrete and implemented Future classes listed above, the Future
24class defined in this module is an entirely abstract interface that anyone may
25implement and use.
26
27The one known incompatibility between this interface and the interface of
28concurrent.futures.Future is that this interface defines its own CancelledError
29and TimeoutError exceptions rather than raising the implementation-private
30concurrent.futures._base.CancelledError and the
31built-in-but-only-in-3.3-and-later TimeoutError.
32"""
33
34import abc
35
36import six
37
38
39class TimeoutError(Exception):
40    """Indicates that a particular call timed out."""
41
42
43class CancelledError(Exception):
44    """Indicates that the computation underlying a Future was cancelled."""
45
46
47class Future(six.with_metaclass(abc.ABCMeta)):
48    """A representation of a computation in another control flow.
49
50  Computations represented by a Future may be yet to be begun, may be ongoing,
51  or may have already completed.
52  """
53
54    # NOTE(nathaniel): This isn't the return type that I would want to have if it
55    # were up to me. Were this interface being written from scratch, the return
56    # type of this method would probably be a sum type like:
57    #
58    # NOT_COMMENCED
59    # COMMENCED_AND_NOT_COMPLETED
60    # PARTIAL_RESULT<Partial_Result_Type>
61    # COMPLETED<Result_Type>
62    # UNCANCELLABLE
63    # NOT_IMMEDIATELY_DETERMINABLE
64    @abc.abstractmethod
65    def cancel(self):
66        """Attempts to cancel the computation.
67
68    This method does not block.
69
70    Returns:
71      True if the computation has not yet begun, will not be allowed to take
72        place, and determination of both was possible without blocking. False
73        under all other circumstances including but not limited to the
74        computation's already having begun, the computation's already having
75        finished, and the computation's having been scheduled for execution on a
76        remote system for which a determination of whether or not it commenced
77        before being cancelled cannot be made without blocking.
78    """
79        raise NotImplementedError()
80
81    # NOTE(nathaniel): Here too this isn't the return type that I'd want this
82    # method to have if it were up to me. I think I'd go with another sum type
83    # like:
84    #
85    # NOT_CANCELLED (this object's cancel method hasn't been called)
86    # NOT_COMMENCED
87    # COMMENCED_AND_NOT_COMPLETED
88    # PARTIAL_RESULT<Partial_Result_Type>
89    # COMPLETED<Result_Type>
90    # UNCANCELLABLE
91    # NOT_IMMEDIATELY_DETERMINABLE
92    #
93    # Notice how giving the cancel method the right semantics obviates most
94    # reasons for this method to exist.
95    @abc.abstractmethod
96    def cancelled(self):
97        """Describes whether the computation was cancelled.
98
99    This method does not block.
100
101    Returns:
102      True if the computation was cancelled any time before its result became
103        immediately available. False under all other circumstances including but
104        not limited to this object's cancel method not having been called and
105        the computation's result having become immediately available.
106    """
107        raise NotImplementedError()
108
109    @abc.abstractmethod
110    def running(self):
111        """Describes whether the computation is taking place.
112
113    This method does not block.
114
115    Returns:
116      True if the computation is scheduled to take place in the future or is
117        taking place now, or False if the computation took place in the past or
118        was cancelled.
119    """
120        raise NotImplementedError()
121
122    # NOTE(nathaniel): These aren't quite the semantics I'd like here either. I
123    # would rather this only returned True in cases in which the underlying
124    # computation completed successfully. A computation's having been cancelled
125    # conflicts with considering that computation "done".
126    @abc.abstractmethod
127    def done(self):
128        """Describes whether the computation has taken place.
129
130    This method does not block.
131
132    Returns:
133      True if the computation is known to have either completed or have been
134        unscheduled or interrupted. False if the computation may possibly be
135        executing or scheduled to execute later.
136    """
137        raise NotImplementedError()
138
139    @abc.abstractmethod
140    def result(self, timeout=None):
141        """Accesses the outcome of the computation or raises its exception.
142
143    This method may return immediately or may block.
144
145    Args:
146      timeout: The length of time in seconds to wait for the computation to
147        finish or be cancelled, or None if this method should block until the
148        computation has finished or is cancelled no matter how long that takes.
149
150    Returns:
151      The return value of the computation.
152
153    Raises:
154      TimeoutError: If a timeout value is passed and the computation does not
155        terminate within the allotted time.
156      CancelledError: If the computation was cancelled.
157      Exception: If the computation raised an exception, this call will raise
158        the same exception.
159    """
160        raise NotImplementedError()
161
162    @abc.abstractmethod
163    def exception(self, timeout=None):
164        """Return the exception raised by the computation.
165
166    This method may return immediately or may block.
167
168    Args:
169      timeout: The length of time in seconds to wait for the computation to
170        terminate or be cancelled, or None if this method should block until
171        the computation is terminated or is cancelled no matter how long that
172        takes.
173
174    Returns:
175      The exception raised by the computation, or None if the computation did
176        not raise an exception.
177
178    Raises:
179      TimeoutError: If a timeout value is passed and the computation does not
180        terminate within the allotted time.
181      CancelledError: If the computation was cancelled.
182    """
183        raise NotImplementedError()
184
185    @abc.abstractmethod
186    def traceback(self, timeout=None):
187        """Access the traceback of the exception raised by the computation.
188
189    This method may return immediately or may block.
190
191    Args:
192      timeout: The length of time in seconds to wait for the computation to
193        terminate or be cancelled, or None if this method should block until
194        the computation is terminated or is cancelled no matter how long that
195        takes.
196
197    Returns:
198      The traceback of the exception raised by the computation, or None if the
199        computation did not raise an exception.
200
201    Raises:
202      TimeoutError: If a timeout value is passed and the computation does not
203        terminate within the allotted time.
204      CancelledError: If the computation was cancelled.
205    """
206        raise NotImplementedError()
207
208    @abc.abstractmethod
209    def add_done_callback(self, fn):
210        """Adds a function to be called at completion of the computation.
211
212    The callback will be passed this Future object describing the outcome of
213    the computation.
214
215    If the computation has already completed, the callback will be called
216    immediately.
217
218    Args:
219      fn: A callable taking this Future object as its single parameter.
220    """
221        raise NotImplementedError()
222